The 640 MEG Shareware Studio 1

home *** CD-ROM | disk | FTP | other *** search

/ The 640 MEG Shareware Studio 1 / The 640 Meg Shareware Studio CD-ROM Volume I (Data Express)(1992).ISO / driver / macpab2.dsk / MACPA2.ZIP / MAAPI / AAPIFUNC.TXT < prev next >

Wrap

Text File | 1992-06-30 | 181KB | 4,258 lines

B64 IBM M-Audio Capture and Playback Adapter Audio Application Programming Interface Functional Description Version 2.00 "C" Language March 9th, 1992 (C) Copyright IBM Corporation. 1991 SUMMARY OF AMENDMENTS _____________________ VERSION 2.00 - APRIL 2, 1990 ____________________________ ∙ Pulse Code Modulation (PCM) support ─ 8 or 16 bit sample size ─ 8000, 11025, 22050, or 44100 sample rates ─ Mono or stereo ─ Support of Microsoft RIFF WAVE file format ∙ Source Mix support Allows the mixing of an analog signal from any of the M-ACPA input sources with the output of playing a PCM file. ∙ Save/Restore support Allows the caller to save the current state of a play or record opera- tion, stop the operation, and then restore the saved state and restart the operation. ∙ Added a function to return the size of audio data structures ∙ Removed support for ADPCM mix function Formatting changes are not identified. Similarly, minor clarifications, grammatical changes, spelling corrections, etc. are not identified. Revisions for version 2.00 are marked with a vertical bar. CHANGE HISTORY ______________ ∙ Version 1.02 - 11 January 90 Initial release in Audio Visual Connection product. ∙ Version 1.03 - July 2, 1990 ─ Added support for MIDI audio type ─ Added Pause/Resume controls ─ Added support for High Quality Music (ADPCM 22K MONO) Summary of Amendments ii ∙ Version 2.00 - 2 April 91 Initial release with M-ACPA. Current version Summary of Amendments iii CONTENTS ________ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2.1 High Level Example . . . . . . . . . . . . . . . . . . . . . . . 3 3. AAPI Functions . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.1 Audio File Functions . . . . . . . . . . . . . . . . . . . . . 4 3.1.1 FAB_TYPE - Determine type of audio file . . . . . . . . . . 4 3.1.2 FAB_OPEN - Open an AVC audio file . . . . . . . . . . . . . 6 3.1.3 FAB_ROPN - Open a RIFF WAVE audio file . . . . . . . . . . 9 3.1.4 FAB_SAVE - Save changes in an audio file . . . . . . . . . 11 3.1.5 FAB_CLOSE - Close an audio file . . . . . . . . . . . . . . 12 3.2 Audio Control Functions . . . . . . . . . . . . . . . . . . . . 13 3.2.1 AUD_SIZE - Return size of audio structures . . . . . . . . 13 3.2.2 AUD_CFIG - Get audio device configuration . . . . . . . . . 14 3.2.3 AUD_INIT - Initialize audio processing . . . . . . . . . . 15 3.2.4 AUD_SET - Set up an audio operation . . . . . . . . . . . . 17 3.2.5 AUD_STRT - Start an audio operation . . . . . . . . . . . . 26 3.2.6 AUD_CTRL - Control an audio operation . . . . . . . . . . 31 3.2.7 AUD_TERM - Terminate audio processing . . . . . . . . . . . 35 4. Control Data Structures . . . . . . . . . . . . . . . . . . . . . 37 4.1 Audio Device Control Block (ADCB) . . . . . . . . . . . . . . . 37 4.2 Audio Start/Stop List Structure (ALST) . . . . . . . . . . . . . 38 4.3 Audio Control Block (ACB) . . . . . . . . . . . . . . . . . . . 39 4.4 Audio Format Structure (AFMT) . . . . . . . . . . . . . . . . . 47 5. Usage Examples . . . . . . . . . . . . . . . . . . . . . . . . . 49 5.1 Check audio hardware and software configuration . . . . . . . . 49 5.2 Play (single channel) . . . . . . . . . . . . . . . . . . . . . 49 5.3 Record/Monitor . . . . . . . . . . . . . . . . . . . . . . . . . 50 5.4 Play (two channel) . . . . . . . . . . . . . . . . . . . . . . . 50 6. AVC Audio File Format . . . . . . . . . . . . . . . . . . . . . . 52 6.1 Audio File Overview . . . . . . . . . . . . . . . . . . . . . . 52 6.1.1 Audio File Types . . . . . . . . . . . . . . . . . . . . . . 52 6.1.1.1 "AUDIO" File . . . . . . . . . . . . . . . . . . . . . . 52 6.1.1.2 "ESCAPE" FILE . . . . . . . . . . . . . . . . . . . . . 52 6.1.2 Audio Object Types . . . . . . . . . . . . . . . . . . . . . 52 6.2 File Data Structures . . . . . . . . . . . . . . . . . . . . . . 55 6.2.1 Directory Control Block . . . . . . . . . . . . . . . . . . 56 6.2.2 File Access Block (FAB) . . . . . . . . . . . . . . . . . . 59 6.2.3 Audio Objects . . . . . . . . . . . . . . . . . . . . . . . 62 6.2.3.1 Object Descriptions . . . . . . . . . . . . . . . . . . 63 7. RIFF WAVE Audio File Format . . . . . . . . . . . . . . . . . . . 68 7.1 Audio File Overview . . . . . . . . . . . . . . . . . . . . . . 68 Appendix A. OS/2 Considerations . . . . . . . . . . . . . . . . . . 69 Contents iv A.1 OS/2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 69 A.2 OS/2 Device Driver . . . . . . . . . . . . . . . . . . . . . . 69 Appendix B. DOS Considerations . . . . . . . . . . . . . . . . . . . 70 B.1 DOS Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 B.2 DOS Device Driver . . . . . . . . . . . . . . . . . . . . . . . 70 B.3 DOS Reentrancy . . . . . . . . . . . . . . . . . . . . . . . . 70 B.4 Expanded Memory . . . . . . . . . . . . . . . . . . . . . . . . 70 Appendix C. Additional Information on PCM Support . . . . . . . . . 71 C.1 Significance of the Different PCM Modes . . . . . . . . . . . . 71 C.1.1 Sample Rate . . . . . . . . . . . . . . . . . . . . . . . . 71 C.1.2 Sample Width . . . . . . . . . . . . . . . . . . . . . . . . 73 C.2 Mu-Law and A-Law Companding . . . . . . . . . . . . . . . . . . 76 C.3 Dither . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 C.4 Volume, Balance, Ramp and Pan . . . . . . . . . . . . . . . . . 80 C.4.1 Master Volume . . . . . . . . . . . . . . . . . . . . . . . 80 C.4.2 Track Volume . . . . . . . . . . . . . . . . . . . . . . . . 81 C.4.3 Ramp Rate . . . . . . . . . . . . . . . . . . . . . . . . . 81 C.4.4 Balance . . . . . . . . . . . . . . . . . . . . . . . . . . 82 C.4.5 Pan Rate . . . . . . . . . . . . . . . . . . . . . . . . . . 83 C.5 Source Mixing . . . . . . . . . . . . . . . . . . . . . . . . . 83 Contents v 1. INTRODUCTION ________________ The Audio Application Programming Interface (AAPI) is a set of high level "C" functions allowing easy application program access to the audio hard- ware function and the stored digitized audio. These functions are intended to be at a level appropriate to shield the application programs from the hardware and the various digitized audio formats, but not so high a level as to implement functions unique to various applications. There are two function sets in the AAPI. The first set allows access to audio files, and the data within the files. The second set of functions is used to control audio operations such as play and record. There are two types of audio file formats supported by the AAPI. The Audio Video Connection file format can be is used to play and record com- pressed audio. These files contain audio data that was compressed using an Adaptive Differential Pulse Code Modulation (ADPCM) technique. The Microsoft Resource Interchange File Format Waveform Audio File Format (RIFF WAVE) is used to play and record un-compressed audio. These files contain Pulse Code Modulation (PCM) data. The suggested way to quickly understand the AAPI and get started writing an application is to browse this document and then study the example pro- grams (play.c, 2play.c, and record.c) provided with the AAPI package. After studying the example programs use this document as a reference for more detailed information. 1. Introduction 1 2. OVERVIEW ____________ The Audio Application Programming Interface (AAPI) is a set of high level "C" functions intended to allow applications to add audio capabilities such as playing and recording with a minimum of effort. The AAPI is file oriented. The application is not required to understand the audio file formats to use the AAPI. The AAPI has functions to open, save, and close audio files. Once the file is open the application is not required to read the audio data to or from the file but only to pass the information about the file returned on the open to subsequent audio functions. The AAPI supports two types of audio files, AVC and RIFF WAVE. The AVC audio file actually consists of two physical files. One of the files con- tains the actual digitized data and is called an "escape" file. The second file contains general information about the audio and sub- components called "objects". Together they are referred to as an AVC audio file. See 6, "AVC Audio File Format" on page 52 for a complete description of the AVC file format. The Microsoft RIFF WAVE file consists of only one physical file. The digitized data and sub-components (called chunks) are contained in the same file. See 7, "RIFF WAVE Audio File Format" on page 68 for more information on the RIFF WAVE format. Although these two file formats are quite different, once the AAPI is used to open either type of file they are represented to the application using the same in memory structure. This structure called a File Access Block (FAB) is filled out and returned when the file is opened. The application does not need to understand the FAB information but just passes a pointer to the FAB to subsequent AAPI function calls. The FAB is described in detail in 6.2.2, "File Access Block (FAB)" on page 59. Once the audio file is open and ready for use the application is ready to use the AAPI control functions. In general these functions take as input a structure called the Audio Control Block (ACB). See 4, "Control Data Structures" on page 37 for a complete description of the ACB and all other control structures. Once initialized the ACB must be maintained between calls with the application only changing defined input fields for a par- ticular function. The current state of the audio process is contained in the ACB. The application can look at the ACB at any time to get status information once an audio operation such as play or record is in progress. 2. Overview 2 2.1 HIGH LEVEL EXAMPLE _______________________ Below is a high level example of using the AAPI function calls. See 5, "Usage Examples" on page 49 and the actual "C" example programs shipped with the AAPI for more detailed examples. Determine type of audio file (FAB_TYPE) If AVC file Open the file (FAB_OPEN) Else RIFF WAVE file Open the file (FAB_ROPN) Endif Initialize the Audio Control Block (AUD_INIT) Determine audio configuration (AUD_CFIG) Set up for playing or recording (AUD_SET) Start playing or recording (AUD_START) While play or record operation in progress Application specific tasks Check Audio Control Block for status and position Control volume or balance (AUD_CTRL) End While Stop playing or recording (AUD_CTRL) Terminate the Audio Control Block (AUD_TERM) Save the file if recording has added data (FAB_SAVE) Close the audio file (FAB_CLOSE) 2. Overview 3 3. AAPI FUNCTIONS __________________ The Audio Application Program Interface functions will be delivered in DOS as a "C" large model static link library and in OS/2 as a dynamic link library (DLL). See Appendix A, "OS/2 Considerations" on page 69 and Appendix B, "DOS Considerations" on page 70 for additional information on using the AAPI under specific operating systems. 3.1 AUDIO FILE FUNCTIONS __________________________ The following functions provide the interface to access audio files, and build the necessary data structures to interface with the audio control functions. | 3.1.1 FAB_TYPE - DETERMINE TYPE OF AUDIO FILE | Description: ____________ | | Attempts to open the requested file and determines if it is a known type | of audio file. | | Synopsis: _________ | | int fab_type(name, type) /* Get type of file */ | char *name; /* Pointer to file name */ | unsigned int *type; /* Pointer to type of file */ | | Input Parameters: _________________ | | Itemized below are the input parameters that must be initialized properly | before the fab_type function is called. | | | NAME - Pointer to fully qualified file name | | TYPE - Pointer to field to return type of file | | Returned types are: 0 = No file exists | 1 = Unknown type | 2 = AVC | 4 = RIFF WAVE | | | | | Output Return Values: _____________________ | | 0, Successful | 3303, Open failed fatal error 3. AAPI Functions 4 | Function: _________ | | 1. Checks for existence of file. | | 2. If exists, opens the file and checks header for type. | | 3. Closes the file. 3. AAPI Functions 5 3.1.2 FAB_OPEN - OPEN AN AVC AUDIO FILE Description: ____________ Creates and/or opens an AVC audio file and initializes/reads all objects associated with the file including the escape file. Synopsis: _________ int fab_open(name, create, /* Open audio file */ expand,object_flag,fabpp, /* */ aud_sz, vol_sz, /* */ pnt_sz, lab_sz) /* */ char name; /* File name */ unsigned char create; /* Create or open file */ unsigned char expand; /* Expand objects in memory */ unsigned char object_flag; /* Specify objects to process */ struct fab *fabpp; /* Pointer to FAB pointer */ unsigned int aud_sz; /* Size to allocate audio object */ unsigned int vol_sz; /* volume object */ unsigned int pnt_sz; /* points object */ unsigned int lab_sz; /* label object */ Input Parameters: _________________ Itemized below are the input parameters that must be initialized properly before the fab_open function is called. NAME - A null terminated string that contains the fully qualified name of the file to access. CREATE - Operation to perform on file 01h = Create then open - Return error if file exists 02h = Open - Return error if file does not exist 03h = Any - Open the file, if it does not exist then create and open EXPAND - Size of objects to allocate 00h = Use existing size when allocating objects 01h = Allocate objects at maximum in memory size regardless of current size 02h = Allocate using values passed by caller or at current size whichever is greater. (AUD_SZ, VOL_SZ, PNT_SZ, LAB_SZ) Sizes for objects not being processed will be ignored. 3. AAPI Functions 6 OBJECT_FLAG - "Audio" and "Escape" objects will always be processed. Additional objects will be processed based on this flag: (Set bits individually) 01h = Process "Volume" object 02h = Process "Points" object 04h = Process "Labels" object FABPP - Pointer to area to store allocated and initialized FAB pointer AUD_SZ - Size in bytes to allocate for the audio object. VOL_SZ - Size in bytes to allocate the volume object. PNT_SZ - Size in bytes to allocate the point object. LAB_SZ - Size in bytes to allocate the label object. Output Return Values: _____________________ 0, Successful 3301, Open failed, file already exists 3302, Open failed, file doesn't exist 3303, Audio file open error 3304, Allocation of FAB failed, insufficient storage 3305, Allocation of object failed, insufficient storage 3306, Audio File read error 3307, Escape file open error Function: _________ 1. Allocates and initializes the FAB and FABOS. 2. Creates/opens the audio file as requested. 3. Allocates the object header and data sections. 4. Reads the objects in from the audio file. 5. Creates/opens the escape file. Notes: ______ ∙ Any audio operation that will expand the "audio" object, such as record or monitor, requires the "volume" object. The "points" and and "labels" objects are always optional. ∙ The audio file name and its extension are used to build the escape file name. If the audio file has a three character extension then the first character of the extension is used in the extension of the 3. AAPI Functions 7 escape file. If the audio file has no extension or less than three characters only ".ad" is used. For example, AUDIO FILE NAME ESCAPE FILE NAME name.!au name.!ad name._au name._ad name.xau name.xad name name.ad name.xx name.ad 3. AAPI Functions 8 | 3.1.3 FAB_ROPN - OPEN A RIFF WAVE AUDIO FILE | Description: ____________ | | Creates and/or opens a RIFF WAVE audio file. | | Synopsis: _________ | | int fab_ropn(name, create, /* Open audio file */ | fabpp, fmtp) /* */ | char name; /* File name */ | unsigned char create; /* Create or open file */ | struct fab *fabpp; /* Pointer to FAB pointer */ | struct afmt *fmtp; /* Pointer to PCM format data */ | | Input Parameters: _________________ | | Itemized below are the input parameters that must be initialized properly | before the fab_ropn function is called. | | | NAME - A null terminated string that contains | the fully qualified name of the file to access. | | CREATE - Operation to perform on file | 01h = Create then open - Return error if file exists | 02h = Open - Return error if file does not exist | 03h = Any - Open the file, if it does not exist | then create and open | | | FABPP - Pointer to area to store allocated | and initialized FAB pointer | | | FMTP - Pointer to area to store PCM format data. | If opening an existing file then the AFMT | structure will be filled in by the FAB_ROPN | call. If creating a new file then the caller | must initialize the structure, selecting what | type of PCM (sampling rate, etc) the file | should have. In both cases the AFMT structure | will then be passed as input to other AAPI calls. | | Output Return Values: _____________________ | | 0, Successful | 3301, Open failed, file already exists | 3302, Open failed, file doesn't exist | 3304, Allocation of FAB failed, insufficient storage | 3307, File open error | | Function: _________ 3. AAPI Functions 9 | 1. Allocates and initializes the FAB and FABOS. | | 2. Creates/opens the audio file as requested. | | Notes: ______ | | ∙ Source Mixing | | An additional function is available when playing PCM files. This | function allows any live input source from the ACPA card such as | microphone or line input to be played and controlled just like playing | any PCM file. To access this function, call FAB_ROPN with NAME = | "MSRCMIX$" and CREATE = 2. Once this device has been opened then use | it just like any other PCM file. 3. AAPI Functions 10 3.1.4 FAB_SAVE - SAVE CHANGES IN AN AUDIO FILE Description: ____________ Locates all the objects in an audio file and saves the ones that have been marked as changed or that have been requested to be saved by the caller. If the file has never been saved, all objects are saved. Synopsis: _________ int fab_save(fabp, oupdates) /* Save changes to an audio file */ struct fab *fabp; /* Pointer to FAB */ unsigned int oupdates; /* Specify objects to update */ Input Parameters: _________________ Itemized below are the input parameters that must be initialized properly before the fab_save function is called. FABP - Pointer to FAB OUPDATES - Objects to update (Set bits individually) 01h = Save audio object 02h = Save volume object 04h = Save escape object 08h = Save points object 10h = Save labels object Output Return Values: _____________________ 0, Successful 3304, Insufficient storage to complete operation 3308, Audio file write failed Function: _________ 1. Locate each object. 2. Mark object for save if file never saved or caller requested save. 3. Write the objects marked for change to disk. Notes: ______ ∙ The Audio Control Block field "oupdates" may be passed directly to this function (as the "oupdates" parameter) after an audio control operation. This will write any objects that were changed during the audio control operation (such as record) to the audio file. 3. AAPI Functions 11 3.1.5 FAB_CLOSE - CLOSE AN AUDIO FILE Description: ____________ Closes the audio file and de-allocates all storage associated with the audio file. Synopsis: _________ int fab_close(fabp) /* Close an audio file */ struct fab *fabp; /* Pointer to FAB */ Input Parameters: _________________ Itemized below are the input parameters that must be initialized properly before the fab_close function is called. FABP - Pointer to FAB Output Return Values: _____________________ 0, Successful Function: _________ 1. Close the escape file (AVC file type). 2. Close the audio file. 3. De-allocate objects. 4. De-allocate the FAB and FABOs. 3. AAPI Functions 12 3.2 AUDIO CONTROL FUNCTIONS _____________________________ The following functions provide the interface to access and control the audio hardware/digital signal processing code and its supported oper- ations. These functions interface with operating system files using the File Access Block (FAB) structure. This interface to files can be set up using the audio file functions provided by this program or the caller can do his own set up and use only these audio control functions. | 3.2.1 AUD_SIZE - RETURN SIZE OF AUDIO STRUCTURES | Description: ____________ | | Returns the length in bytes of the requested structure. | | Synopsis: _________ | | int aud_size(int) /* Return size of structure */ | int structure_type; /* Type of structure */ | | Input Parameters: _________________ | | Itemized below are the parameters that must be initialized properly before | the aud_size function is called. | | | structure_type - Type of audio structure to size | 01h - Audio Device Structure | 02h - Audio Control Block | 03h - Save/Restore Area | 04h - Start/Stop List | | Output Return Values: _____________________ | | | N, Size in bytes of structure 3. AAPI Functions 13 3.2.2 AUD_CFIG - GET AUDIO DEVICE CONFIGURATION Description: ____________ Access and return configuration information and status on the audio device and any corresponding device driver. Synopsis: _________ int aud_cfig(adcbptr) /* Get configuration information */ struct adcb *adcbptr; /* Pointer to Audio Device CB */ Input Parameters: _________________ Input ADCB: ___________ No input fields. Output Return Values: _____________________ 0, Successful, audio device installed and active 3224, Failed, no audio device installed 3225, Failed, audio device interrupts are disabled 3226, Failed, device driver not responding Output ADCB: ____________ Itemized below are the ADCB fields set by the aud_cfig function. DEVICE_ID - Microchannel device ID 6E6Ch = IBM M-Audio Capture and Playback Adapter IOBASE - Audio card base address for program I/O INTLEVEL - Audio card hardware interrupt level OS2RTN - OS/2 error code Function: _________ 1. If operating system is OS/2, verifies the device driver is installed and active. If an error occurs accessing the device driver, returns (3226) and also returns the OS/2 error code in the ADCB. 2. Verifies that an audio device is installed, returns (3224) otherwise. 3. Verifies that interrupts are not disabled, returns (3225) otherwise. 4. If an audio device is installed and active, sets configuration infor- mation in the ADCB and returns (0). 3. AAPI Functions 14 3.2.3 AUD_INIT - INITIALIZE AUDIO PROCESSING Description: ____________ Initialize a caller passed Audio Control Block for subsequent AAPI calls. Synopsis: _________ int aud_init(acbptr) /* Initialize audio processing */ struct acb *acbptr; /* Pointer to Audio Control Block */ Input Parameters: _________________ Input ACB: __________ Itemized below are the ACB fields that must be initialized properly before the aud_init function is called. ACB2PTR - ACB pointer of second track to process 00000000h = Single track All other ACB fields will be initialized by this function. The following are the default values for the audio controls if the user does not explicitly change them: ∙ I/O buffer length if AAPI allocates storage - 32K bytes ∙ Master volume level - 100% ∙ Track volume level - 100% ∙ Channel balance - 50% ∙ Output channel pair - A(100%)/B(0%) ∙ Audio compression type - AVC ADPCM/11K The ACB must be maintained between calls (aud_init through aud_term) with the user changing only defined input fields for a particular function call. Output Return Values: _____________________ 0, Successful Output ACB: ___________ Itemized below are the ACB fields set by the aud_init function. All output fields marked with "*" are updated at one tenth of a second inter- vals requiring no function call once an asynchronous (play, record) audio operation has been started. 3. AAPI Functions 15 * POSITION - Current position in audio (milliseconds) * STATE - Current state of signal processor 00h = stopped 01h = playing 02h = recording 03h = stopping * TIMELEFT - Time left before I/O necessary (ms) OUPDATED - Indication of which objects were changed by AAPI ACB2RC - Return code for second ACB operation Function: _________ 1. All input and output fields (except ACB2PTR) will be initialized. 2. If a secondary ACB is passed in ACB2PTR that ACB will also be initial- ized. Notes: ______ ∙ This function will always return successful. 3. AAPI Functions 16 3.2.4 AUD_SET - SET UP AN AUDIO OPERATION Description: ____________ Set up the signal processor and audio objects so that subsequent calls to start and stop audio operations happen immediately. Synopsis: _________ int aud_set(acbptr) /* Set up audio operations */ struct acb *acbptr; /* Pointer to Audio Control Block */ Input Parameters: _________________ Input ACB: __________ Itemized below are the ACB fields that must be initialized properly before the aud_set function is called. Only areas listed should be altered. All other initialization of fields is done on a aud_init call which is required before any other type of AAPI control function calls are made. The ACB must be maintained between calls (aud_init through aud_term) with the user changing only defined input fields for a particular function call. 3. AAPI Functions 17 CHANNEL - Signal processor channel identifier 00h = Channel A 01h = Channel B | FFh = An available channel will be selected and | returned in this field. DSPMODE - Set up signal processor for this audio operation 01h = Play 02h = Record 03h = Monitor SEEKTYPE - Set up audio object(s) at this position 00h = Initialize for new/different audio object 01h = Seek to new position in current audio object 02h = Continue at next position in current object 03h = Release resources only 04h = Release resources, then initialize new object AUDTYPE - The type of audio compression to use. 00h = Use current for existing or default for new 01h = Use ADPCM 11K (AVC mono music) 02h = Use ADPCM 5.5K (AVC mono voice) 03h = Use ADPCM 22K (AVC stereo music) 04h = Use ADPCM 22K (AVC mono high quality music) | 3Ch = Use PCM (RIFF WAVE file) Ignored if "DSPMODE" is not record or monitor. | ADPCM (types 0-4) can only be used with AVC format | audio files. PCM (type 3Ch) can only be used with | RIFF WAVE files. 3. AAPI Functions 18 INTLEVEL - Audio card hardware interrupt level INPSRCE - Audio card input source 00h = Microphone input - normal gain 01h = Line level input - left channel 02h = Line level input - right channel 03h = Line level input - both channel 04h = Microphone input - low gain Ignored if "DSPMODE" is not record or monitor | unless doing "source mix". Valid options for | source mix are 0, 3, and 4. PIOBASE - Audio card base address for port I/O CONTROLS - Control changes requested (Set bits individually) 01h = Master volume 02h = Track volume - 1 04h = Track volume - 2 08h = Channel balance 10h = Set stop position 40h = Pause current operation 80h = Resume current operation Settings "40h and 80h" are mutually exclusive. All or none of these controls may be requested. OPRPARMS - Operation parameters flag (Set bits individually) 02h = Do not update audio/volume object totals 04h = PS/2 speaker enabled, ignored on non-PS/2 10h = Monitor - record pre-compression 20h = Monitor - record post-compression 200h = Cancel operation if switched to background 400h = Setup VOICE/MIDI DSP environment Settings "10h and 20h" are mutually exclusive and ignored if DSPMODE is not monitor. FILEPTR - File Access Block pointer SUBTYPE - FABO subtype of objects AUDSTART - Start position for seek (milliseconds) 00000000h = Start of data AUDEND - End position for seek (milliseconds) 00000000h = End of data BUFFLEN - I/O buffer length BUFFPTR - I/O buffer pointer 3. AAPI Functions 19 EMMHAN - Expanded memory manager handle Ignored if "MEMID" is not set to "LIM". EMMCNT - Expanded memory manager page count Ignored if "MEMID" is not set to "LIM". MEMID - Memory type id 00h = not allocated 01h = main memory 02h = LIM memory 03h = Device If memory is not allocated by the caller, the AAPI will attempt to allocate the size specified in BUFFLEN from main memory. If BUFFLEN is zero a default length of 32K bytes will be allocated. If the AAPI allocates the memory it will be released when the caller does an aud_term. CTLPARMS - Control parameters flag (Set bits individually) 01h = Stop - Ignore other control requests (on) Stop - Honor pending control requests (off) Setting "01h" is ignored if CONTROLS is not set for "set stop position". 02h = Purge control queue for this channel 08h = Pause/resume all channels (on) Pause/resume only this channel (off) Setting "08h" is ignored if CONTROLS is not set for "pause" or "resume". | 10h = Restore the previous control state. On | subsequent calls to "aud_set" this flag can | be set to restore the control settings in | effect when the last operation was stopped. | If the caller passed a pointer to a save area | (SVRSPTR) on the initial call to "aud_set" and | is resuming at the same place in | the same file (SEEKTYPE=2), then the | current state and any pending controls | that were queued but not yet executed will | be re-queued (including stop requests). If no | save area was passed or not restarting where | the last operation was stopped then only the | last control settings will be restored. | | MASVOL - Master volume level (ADPCM 0 - 100/PCM 0 - 120) Required if "CONTROLS" is set for master volume. TRKVOL1 - Track volume level (0 - 100) Required if "CONTROLS" is set for track volume-1. TRKVOL1S - Start position for track volume change (ms) Required if "CONTROLS" is set for track volume-1. 3. AAPI Functions 20 TRKVOL1E - End position for track volume change (ms) Required if "CONTROLS" is set for track volume-1. TRKVOL2 - Track volume level (0 - 100) This field applies to exactly the same control as TRKVOL1. This second field gives the caller the ability to specify two volume fades at different positions in the audio. If the positions overlap the caller will be overriding the previous control change that was requested. Required if "CONTROLS" is set for track volume-2. 3. AAPI Functions 21 TRKVOL2S - Start position for track volume change (ms) Required if "CONTROLS" is set for track volume-2. TRKVOL2E - End position for track volume change (ms) Required if "CONTROLS" is set for track volume-2. CHNBAL - Channel balance (pan) level (100 - 0) Required if "CONTROLS" is set for channel balance. OUTCHAN - Output channel pair for balance 0 = Channel left/right 1 = Channel right/left Required if "CONTROLS" is set for channel balance. CHNBALS - Start position for channel balance change (ms) Required if "CONTROLS" is set for channel balance. CHNBALE - End position for channel balance change (ms) Required if "CONTROLS" is set for channel balance. STOPPOS - Position to stop current operation (ms) Required if "CONTROLS" is set for set stop position. ACB2PTR - ACB pointer of second track to process 00000000h = Single track LISTPTR - Pointer to an Audio Start/Stop List structure. This structure contains additional start/stop positions to be used during play operations. This structure also contains a pointer to the next List structure. This linked list of positions is not used until the position passed in "AUDEND" has been reached. 00000000h = No additional positions DSP_PATH - Pointer to a fully qualified directory name to use when accessing DSP files. If this field is zero then the current directory is used. | SVRSPTR - Pointer to a Save/Restore area to be used to restart | play and record. See the CTRPARMS description for | more information. | FMTPTR - Pointer to an audio format area that contains | additional information about the type of audio | being played or recorded. Required only if | using a RIFF WAVE file. Set to 0 for AVC files. 3. AAPI Functions 22 Output Return Values: _____________________ 0, Successful 3201, "Audio" object read error 3202, "Audio" object not found 3203, "Volume" object read error 3204, "Volume" object not found 3205, "Escape" object read error 3206, "Escape" object not found 3207, "Escape" file read error 3208, I/O buffer allocation failed 3209, "audstart" position invalid 3210, "audend" position invalid 3211, "Escape" file seek error 3212, DSP card not responding 3213, DSP buffer allocation failed 3214, DSP program not found 3215, DSP program not readable 3216, "dspmode" invalid or audio file/microcode versions don't match 3218, Unable to install audio interrupt service routine 3219, "Escape" file write error 3220, Control queue overflow, control ignored 3221, EMS Save Page Map failed 3222, EMS Map Page failed 3223, EMS Restore Page Map failed 3224, Microchannel system, but no audio device installed 3226, Device driver not responding 3233, DSP running and requested operation requires reload of DSP 3234, MIDI audio type can not be played on Channel A or in DOS 3235, Device driver error occurred when writing MIDI data 3236, Operating system call failed, system inconsistency Output ACB: ___________ Itemized below are the ACB fields set by the aud_set function. All output fields marked with "*" are updated at one tenth of a second intervals requiring no function call once an operation (play, record) has been started. * POSITION - Current position in audio (ms) * STATE - Current state of signal processor 00h = stopped 01h = playing 02h = recording 03h = stopping * TIMELEFT - Time left before I/O necessary (ms) OUPDATED - Indication of which objects were changed by AAPI ACB2RC - Return code for second ACB operation 3. AAPI Functions 23 Function: _________ 1. Based on the requested DSPMODE, if the signal processor is not already in the required mode, the current mode is terminated and the new mode is initialized. 2. Based on SEEKTYPE, if the current audio object(s) are no longer needed, the current objects are purged (see notes for more detail) and the requested objects are read as necessary. 3. An open (if not already open) and seek will be done in the escape file to the caller's requested position. Using the caller's "BUFFPTR" and "BUFFLEN" the maximum amount of audio data will be pre-loaded if a play operation is being done. Notes: ______ | ∙ The size of the Audio I/O buffer(s) in main memory can be greater than | 64K. If BUFFLEN is set for greater than 64K then it must be on 64K | boundaries (64K, 128K, 192K...) and the caller must allocate the | buffer and put the pointer to it in BUFFPTR. ∙ LIM memory can be passed for the Audio I/O buffer(s). The AAPI will always save the current LIM mapping, remap as required for the Audio I/O buffer, and then restore the original mapping before exit. No remapping for LIM is done for other data items such as FABOs. If other data used by the AAPI has been allocated in LIM, it must have the same mapping as the Audio I/O buffer, or, be mapped correctly upon entry to the AAPI and remain mapped correctly until the AAPI is termi- nated. ∙ An error on any ACB will terminate the processing and the AAPI will return to the caller without processing any additional ACBs. | ∙ During ADPCM recording the volume and balance controls are not used. | The master volume controls the monitor level of the recording but this | does not affect the recorded data. | | ∙ During PCM recording the master volume, volume, and balance controls | are in effect and control the monitor volume and balance as well as | the recorded data. ∙ Due to DSP code size and performance restrictions on the M-ACPA signal processor and the host PC not all functions can be loaded and per- formed simultaneously. The restrictions are: ─ Recording is limited to one track at a time. ─ Playing two AVC ADPCM tracks is allowed as long as neither track is using stereo or high quality audio compression. | ─ AVC ADPCM and RIFF WAVE files can not be played at the same time. 3. AAPI Functions 24 | ─ Playing two RIFF WAVE tracks is allowed as long as neither track | is stereo, mu-law, or a-law. | | ─ 44KH stereo mu-law or a-law is not allowed. | | ─ Monitoring the recorded output of an ADPCM stereo compression | track or any PCM track while it is being recorded is not allowed. | The source can be monitored during the recording but not the | result. | | ─ Source mix can only be used on one PCM track at a time. ─ Playing one track and recording a different track (dubbing) simul- taneously is not allowed. ─ MIDI audio files can only be played in OS/2, not in DOS. ─ MIDI audio files can only be played on Track B. The only audio type that can be played simultaneously with MIDI is ADPCM voice on Track A. There are two DSP environments (DSP load modules) where voice can be played, VOICE/MIDI and VOICE/(VOICE or MUSIC). Once one of the environments has been set up and is started, changing to a different environment can not be done without stopping the DSP. For example, if the VOICE/MIDI environment is loaded and VOICE is playing, only MIDI can be played simultaneously. If a MUSIC file is now to be played the DSP must be stopped and reloaded. If the VOICE/MUSIC environment had been loaded in the first place then both VOICE and MUSIC could be played without stopping the DSP. If MIDI or MUSIC is the first audio type to be requested for play, then there is no choice on which environment to load. If VOICE is the first request then the caller can pick the environment by setting on or off the "Setup VOICE/MIDI" flag in the OPRPARMS field. 3. AAPI Functions 25 3.2.5 AUD_STRT - START AN AUDIO OPERATION Description: ____________ Start audio processing for the operation requested by the caller. Synopsis: _________ int aud_strt(acbptr) /* Start audio processing */ struct acb *acbptr; /* Pointer to Audio Control Block */ Input Parameters: _________________ Input ACB: __________ Itemized below are the ACB fields that must be initialized properly before the aud_strt function is called. All other fields should have been ini- tialized on a "aud_init" call and a previous "aud_set" call. The ACB must be maintained between calls (aud_init through aud_term) with the user changing only defined input fields for a particular function call. CONTROLS - Control changes requested (Set bits individually) 01h = Master volume 02h = Track volume - 1 04h = Track volume - 2 08h = Channel balance 10h = Set stop position 40h = Pause current operation 80h = Resume current operation Settings "40h and 80h" are mutually exclusive. CTLPARMS - Control parameters flag (Set bits individually) 01h = Stop - Ignore other control requests (on) Stop - Honor pending control requests(off) Setting "01h" is ignored if CONTROLS is not set for "set stop position". 02h = Purge control queue for this channel 08h = Pause/resume all channels (on) Pause/resume only this channel (off) Setting "08h" is ignored if CONTROLS is not set for "pause" or "resume". | MASVOL - Master volume level (ADPCM 0 - 100/PCM 0 - 120) Required if "CONTROLS" is set for master volume. 3. AAPI Functions 26 TRKVOL1 - Track volume level (0 - 100) Required if "CONTROLS" is set for track volume-1. TRKVOL1S - Start position for track volume change (ms) Required if "CONTROLS" is set for track volume-1. TRKVOL1E - End position for track volume change (ms) Required if "CONTROLS" is set for track volume-1. TRKVOL2 - Track volume level (0 - 100) This field applies to exactly the same control as TRKVOL1. This second field gives the caller the ability to specify two volume fades at different positions in the audio. If the positions overlap the caller will be overriding the previous control change that was requested. Required if "CONTROLS" is set for track volume-2. TRKVOL2S - Start position for track volume change (ms) Required if "CONTROLS" is set for track volume-2. TRKVOL2E - End position for track volume change (ms) Required if "CONTROLS" is set for track volume-2. CHNBAL - Channel balance (pan) level (100 - 0) Required if "CONTROLS" is set for channel balance. OUTCHAN - Output channel pair for balance 0 = Channel left/right 1 = Channel right/left Required if "CONTROLS" is set for channel balance. CHNBALS - Start position for channel balance change (ms) Required if "CONTROLS" is set for channel balance. CHNBALE - End position for channel balance change (ms) Required if "CONTROLS" is set for channel balance. STOPPOS - Position to stop current operation (ms) Required if "CONTROLS" is set for set stop position. ACB2PTR - ACB pointer of second track to process 00000000h = Single track Output Return Values: _____________________ 3. AAPI Functions 27 0, Successful 3220, Control queue overflow, control ignored 3227, Disk full - out of space 3228, Audio object at maximum size 3229, DSP overload - Attempted to play a stereo or HQ music track and another track simultaneously 3230, Recording media too slow, recording data lost 3231, Operation cancelled, process not in foreground 3232, Audio file at maximum file length (address space) 3233, DSP running and requested operation requires reload of DSP 3234, MIDI audio type can not be played on Channel A or in DOS 3235, Device driver error occurred when writing MIDI data 3236, Operating system call failed, system inconsistency Output ACB: ___________ Itemized below are the ACB fields set by the aud_strt function. All output fields marked with "*" are updated at one tenth of a second inter- vals requiring no function call once an asynchronous audio operation (play, record) has been started. * POSITION - Current position in audio (ms) * STATE - Current state of signal processor 00h = stopped 01h = playing 02h = recording 03h = stopping * TIMELEFT - Time left before I/O necessary (ms) OUPDATED - Indication of which objects were changed by AAPI * BACKRC - Set if error occurs during an operation, between explicit calls to the AAPI. ACB2RC - Return code for second ACB operation Function: _________ 1. Any control changes requested are executed or queued for execution before the operation is started. This is true for both the primary ACB and the secondary ACB. 2. Based on the requested command(s) on a previous "aud_set" call, the requested operation(s) are started. 3. If an error occurs during the operation, but not during a explicit call to the AAPI, then the "backrc" field is set. For example, if the disk becomes full during a record operation, the operation will be stopped, and the appropriate return code set into the "backrc" field. The caller does not need to poll this return code continuously during the operation. If an error occurs, the operation will be terminated 3. AAPI Functions 28 without waiting for the caller to request a stop. The caller can simple look at this field after the operation has stopped to see if the operation completed successfully. Notes: ______ ∙ Play, record, and monitor are asynchronous operations. That is, they run independently until stopped by an aud_stop call. The user can monitor the progress of the operation using the ACB output fields described above. The user can control the operation (volume, I/O request) with additional calls, but the operation continues during and after these additional calls. ∙ Due to DSP code size and performance restrictions on the M-ACPA signal processor and the host PC not all functions can be loaded and per- formed simultaneously. The restrictions are: ─ Recording is limited to one track at a time. ─ Playing two AVC ADPCM tracks is allowed as long as neither track is using stereo or high quality audio compression. | ─ AVC ADPCM and RIFF WAVE PCM files can not be played at the same | time. | | ─ Playing two RIFF WAVE tracks is allowed as long as neither track | is stereo, mu-law, or a-law. | | ─ 44KH stereo mu-law or a-law is not allowed. | | ─ Monitoring the recorded output of an ADPCM stereo compression | track or any PCM track while it is being recorded is not allowed. | The source can be monitored during the recording but not the | result. | | ─ Source mix can only be used on one PCM track at a time. ─ Playing one track and recording a different track (dubbing) simul- taneously is not allowed. ─ MIDI audio files can only be played in OS/2, not in DOS. ─ MIDI audio files can only be played on Track B. The only audio type that can be played simultaneously with MIDI is ADPCM voice on Track A. There are two DSP environments (DSP load modules) where voice can be played, VOICE/MIDI and VOICE/(VOICE or MUSIC). Once one of the environments has been set up and is started, changing to a different environment can not be done without stopping the DSP. For example, if the VOICE/MIDI environment is loaded and VOICE is playing, only MIDI can be played simultaneously. If a MUSIC file is now to be played the DSP must be stopped and reloaded. If the VOICE/MUSIC environment had been loaded in the first place then both VOICE and MUSIC could be played without stopping the DSP. If MIDI or MUSIC is the first audio type to be 3. AAPI Functions 29 requested for play, then there is no choice on which environment to load. If VOICE is the first request then the caller can pick the environment by setting on or off the "Setup VOICE/MIDI" flag in the OPRPARMS field. 3. AAPI Functions 30 3.2.6 AUD_CTRL - CONTROL AN AUDIO OPERATION Description: ____________ Change the current audio settings or control the operation in progress. Synopsis: _________ int aud_ctrl(acbptr) /* Change audio controls */ struct acb *acbptr; /* Pointer to Audio Control Block */ Input Parameters: _________________ Input ACB: __________ Itemized below are the ACB fields that must be initialized properly before the aud_ctrl function is called. All other fields should have been ini- tialized on previous function calls. The ACB must be maintained between calls (aud_init through aud_term) with the user changing only defined input fields for a particular function call. CONTROLS - Control changes requested (Set bits individually) 01h = Master volume 02h = Track volume - 1 04h = Track volume - 2 08h = Channel balance 10h = Set stop position 20h = Perform I/O 40h = Pause current operation 80h = Resume current operation Settings "40h and 80h" are mutually exclusive. CTLPARMS - Control parameters flag (Set bits individually) 01h = Stop - Ignore other control requests (on) Stop - Honor pending control requests(off) Setting "01h" is ignored if CONTROLS is not set for "set stop position". 02h = Purge control queue for this channel 04h = This call is being made from an interrupt service routine in DOS. If DOS is "busy" and can not be re-entered then the request will not be processed and error code 3217 will be returned. 08h = Pause/resume all channels (on) Pause/resume only this channel (off) Setting "08h" is ignored if CONTROLS is not set for "pause" or "resume". MASVOL - Master volume level (0 - 100) Required if "CONTROLS" is set for master volume. 3. AAPI Functions 31 TRKVOL1 - Track volume level (0 - 100) Required if "CONTROLS" is set for track volume-1. TRKVOL1S - Start position for track volume change (ms) Required if "CONTROLS" is set for track volume-1. TRKVOL1E - End position for track volume change (ms) Required if "CONTROLS" is set for track volume-1. TRKVOL2 - Track volume level (0 - 100) This field applies to exactly the same control as TRKVOL1. This second field gives the caller the ability to specify two volume fades at different positions in the audio. If the positions overlap the caller will be overriding the previous control change that was requested. Required if "CONTROLS" is set for track volume-2. TRKVOL2S - Start position for track volume change (ms) Required if "CONTROLS" is set for track volume-2. TRKVOL2E - End position for track volume change (ms) Required if "CONTROLS" is set for track volume-2. CHNBAL - Channel balance (pan) level (100 - 0) Required if "CONTROLS" is set for channel balance. OUTCHAN - Output channel pair for balance 0 = Channel left/right 1 = Channel right/left Required if "CONTROLS" is set for channel balance. CHNBALS - Start position for channel balance change (ms) Required if "CONTROLS" is set for channel balance. CHNBALE - End position for channel balance change (ms) Required if "CONTROLS" is set for channel balance. STOPPOS - Position to stop current operation (ms) Required if "CONTROLS" is set for set stop position. IOTIME - The amount of audio data in milliseconds to read into or write from the audio buffers. 00000000h = Maximum amount of data Required if "CONTROLS" is set for perform I/O. ACB2PTR - ACB pointer of second track to process 00000000h = Single track Output Return Values: _____________________ 3. AAPI Functions 32 0, Successful 3207, "Escape" file read error 3211, "Escape" file seek error 3217, I/O not possible at this time 3219, "Escape" file write error 3220, Control queue overflow, control ignored 3235, Device driver error occurred when writing MIDI data 3236, Operating system call failed, system inconsistency Output ACB: ___________ Itemized below are the ACB fields set by the aud_ctrl function. All output fields marked with "*" are updated at one tenth of a second inter- vals requiring no function call once an operation (play, record) has been started. * POSITION - Current position in audio (ms) * STATE - Current state of signal processor 00h = stopped 01h = playing 02h = recording 03h = stopping * TIMELEFT - Time left before I/O necessary (ms) OUPDATED - Indication of which objects were changed by AAPI ACB2RC - Return code for second ACB operation Function: _________ 1. Control changes are queued for execution based on their order (01, 02, 04...) in the "CONTROLS" field and the requested start position in the audio for that control. Use separate aud_ctrl calls if a different order of execution is required. Identical control changes for dif- ferent channels requested by setting the control in both the primary and secondary ACBs will be done as closely as possible. For example, all "master volume" control changes will be queued for execution before the next control is considered. Notes: ______ ∙ If playing, and a request to "perform I/O" is not made before the data in the audio buffers is exhausted, the AAPI will begin asynchronously doing the minimum amount of I/O needed to keep the audio card ser- viced. Subsequent "perform I/O" requests may be able to replenish the buffers and re-synchronize the process but if this is not possible asynchronous I/O will continue to be done until the play operation is stopped. ∙ If recording, and a request to "perform I/O" is not made before the audio buffers are filled to capacity, the AAPI will begin asynchro- 3. AAPI Functions 33 nously doing the minimum amount of I/O needed to partially empty the audio buffers and accept more audio data from the audio card. Subse- quent "perform I/O" requests may be able to flush the buffers and re- synchronize the process but if this is not possible asynchronous I/O will continue to be done until the record operation is stopped. ∙ A stop control request will not stop the operation immediately if the CTLPARMS flag is set to honor other controls. Any controls requested to be executed or in progress will be allowed to complete before the stop. This means that the audio card must not be allowed to run out of audio data or overflow the audio buffers before the last control is completed. The caller must be certain that sufficient data or room is in the audio buffers before doing a stop or continue to do aud_ctrl calls. The AAPI will do I/O asynchronously to continue servicing the audio card if necessary if the caller is unable to do aud_ctrl calls. 3. AAPI Functions 34 3.2.7 AUD_TERM - TERMINATE AUDIO PROCESSING Description: ____________ Terminate audio operations for this ACB Synopsis: _________ int aud_term(acbptr) /* Terminate audio processing */ struct acb *acbptr; /* Pointer to Audio Control Block */ Input Parameters: _________________ Input ACB: __________ Itemized below are the ACB fields that must be initialized properly before the aud_term function is called. All other fields should have been ini- tialized on previous calls. The ACB must be maintained between calls (aud_init through aud_term) with the user changing only defined input fields for a particular function call. ACB2PTR - ACB pointer of second track to process 00000000h = Single track Output Return Values: _____________________ 0, Successful Output ACB: ___________ Itemized below are the ACB fields set by the aud_term function. All output fields marked with "*" are updated at one tenth of a second inter- vals requiring no function call once an operation (play, record) has been started. OUPDATED - Indication of which objects were changed by AAPI ACB2RC - Return code for second ACB operation Function: _________ 1. Any interrupt handler/device driver for the signal processor is deac- tivated. 2. Any objects that were read in by the AAPI and were not changed are purged from memory. If the object was already open, then it is left open but marked as updated if it was changed. 3. AAPI Functions 35 3. If the AAPI allocated the I/O buffer it is de-allocated. Notes: ______ 3. AAPI Functions 36 4. CONTROL DATA STRUCTURES ___________________________ The following section provides descriptions of the control blocks used with the audio control type functions of the AAPI. 4.1 AUDIO DEVICE CONTROL BLOCK (ADCB) ______________________________________ The ADCB is the structure used to retrieve configuration information about the audio device installed in the system. The only audio device currently supported is the IBM M-Audio Capture and Playback Adapter. ; ** Audio Device Control Block ** ; _________________________ adcb struc ; *** OUTPUT PARAMETERS *** device_id dw ; Device ID of audio card ; 6E6Ch = IBM M-ACPA (PS/2) iobase dw ; I/O address base intlev dw ; Hardware interrupt level os2rtn dw ; OS/2 error code res db 10 dup ; Reserved adcb ends The parameters in the AAPI Device Control Block can have the following values: 1. DEVICE_ID - The microchannel device ID of the installed adapter. 2. IOBASE - The starting address of eight I/O addresses that the adapter has been configured to use. 3. INTLEV - The hardware interrupt level that the adapter has been con- figured to use. 4. OS2RTN - If a call to OS/2 fails while accessing the device driver, the OS/2 error code will be returned in this field. 5. RESERVED - A reserved area for future expansion. 4. Control Data Structures 37 4.2 AUDIO START/STOP LIST STRUCTURE (ALST) ___________________________________________ The ALST is the structure used to pass additional start/stop times to the Audio API during play operations. ; ** Audio Start/Stop List Structure ; _________________________ alst struc ; audstart dd ; Start position for seek (milliseconds) audend dd ; End position for seek (milliseconds) nextlist dd ; Ptr to next ALST alst ends The fields in the ALST can have the following values: 1. AUDSTART - Position to start next play operation. 2. AUDEND - Position to end the play operation. 3. NEXTLIST - Pointer to next structure or null. If null the operation will end. If not null, playing will continue at the next "audstart" position. NEXTLIST may point to itself, or another structure already processed to create a loop. 4. Control Data Structures 38 4.3 AUDIO CONTROL BLOCK (ACB) ______________________________ The ACB is the primary control block used for communication between the AAPI and the calling application program. The control block has input parameters which are used to control how the AAPI interacts with the audio hardware and has output parameters which the AAPI uses to convey informa- tion back to the feature program. The control block has the following structure: ; ** Audio Control Block ** ; _________________________ acb struc ; *** INPUT PARAMETERS *** channel db ; Input channel identifier ; 00h = Channel A ; 01h = Channel B | ; FFh = Select and return channel dspmode db ; Signal processor operation ; 01h = Play ; 02h = Record ; 03h = Monitor seektype db ; Type of seek in audio object ; 00h = Init/seek in new object ; 01h = Seek in current object ; 02h = Continue in current object ; 03h = Release resources only ; 04h = Release, then init and seek audtype db ; Type of audio compression to use ; 00h = Current/Default ; 01h = ADPCM 11.0K (music) ; 02h = ADPCM 5.5K (voice) ; 03h = ADPCM 22.0K (stereo music) ; 04h = ADPCM 22.0K (High Qual music) ; 60h = PCM intlevel db ; Audio card interrupt level inpsrce db ; Audio card input source ; 00h = Microphone input - normal ; 01h = Line level input - left ; 02h = Line level input - right ; 03h = Line level input - both ; 04h = Microphone input - low piobase dw ; Audio card base address controls dw ; Control changes requested ; (Set bits individually) ; 01h = Master volume ; 02h = Track volume - 1 ; 04h = Track volume - 2 ; 08h = Channel Balance ; 10h = Set stop position ; 20h = Perform I/O ; 40h = Pause current operation ; 80h = Resume current operation 4. Control Data Structures 39 oprparms dw ; Operation parameters ; (Set bits individually) ; 02h = Do not update audio object ; totals during record operations ; 04h = PS/2 speaker output enabled ; 10h = Monitor, record pre-compression ; 20h = Monitor, recrd post-compression ; 200h = Cancel operation if process is ; not in foreground ; 400h = Setup VOICE/MIDI DSP ; environment if voice is started ; first fileptr dd ; File Access Block pointer subtype dw ; FABO subtype of objects audstart dd ; Start position for seek (milliseconds) ; 00000000h = Start of data audend dd ; End position for seek (milliseconds) ; 00000000h = End of data bufflen dd ; I/O buffer length buffptr dd ; I/O buffer pointer emmhan dw ; Expanded memory manager handle emmcnt dw ; Expanded memory manager page count memid dw ; Memory type id ; 00h = not allocated ; 01h = main memory ; 02h = LIM memory db 6 dup ; (reserved -- 00h) ctlparms db ; Control parameters ; (Set bits individually) ; 01h = Stop - Ignore other ctrls (on) ; Stop - Honor pending ctrls(off) ; 02h = Purge control queue for this ; channel before processing ; new controls ; 04h = This call is being done from ; within an interrupt service ; in DOS. ; 08h = Pause/Resume all channels (on) ; Pause/Resume only this ch (off) | ; 10h = Restore previous controls 4. Control Data Structures 40 masvol db ; Master volume level | ; ADPCM (0-100) PCM (0-100) trkvol1 dw ; Track volume level 1 (0 - 100) trkvol1s dd ; Start position for trk vol1 change(ms) trkvol1e dd ; End position for trk vo1l change (ms) trkvol2 dw ; Track volume level 2 (0 - 100) trkvol2s dd ; Start position for trk vol2 change(ms) trkvol2e dd ; End position for trk vo12 change (ms) chnbal db ; Channel balance (pan) level (100 - 0) outchan db ; Output channel pair for balance ; 0 = Channel Left/right ; 1 = Channel Right/Left chnbals dd ; Start position for chan bal change (ms) chnbale dd ; End position for channel bal change(ms) stoppos dd ; Position to stop operation (ms) iotime dd ; Length of audio read/write (ms) ; 00000000h = Maximum length acb2ptr dd ; ACB pointer of second track to process ; 00000000h = Single track listptr dd ; Ptr to list of start/stop positions dsp_path dd ; Ptr to directory path for DSP code | svrsptr dd ; Ptr to save/restore area for controls | fmtptr dd ; Ptr to audio format data | in_reser db 20 dup ; Reserved area for input parm expansion ; *** OUTPUT PARAMETERS *** position dd ; Current position in audio (ms) state db ; Current state of signal processor ; 00h = stopped ; 01h = playing ; 02h = recording ; 03h = stopping backrc dw ; Background process return code acb2rc dw ; Return code for second track operation timeleft dd ; Time left before I/O necessary (ms) oupdates dw ; Audio objects updated flag ; (Set bits individually) ; 01h = AUDIO object changed ; 02h = VOLUME object changed ; 04h = ESCAPE object changed out_rese db 8 dup ; Reserved area for output parm expansion | db 256 dup ; AAPI work area acb ends The parameters in the AAPI control block can have the following values: 1. CHANNEL - channel/track identifier This parameter selects the channel on the signal processor where the operation will be performed. ∙ 0 - Channel A 4. Control Data Structures 41 ∙ 1 - Channel B | ∙ 255 - The AAPI will select and return available channel in this | field. 2. DSPMODE - Mode for audio signal processor ∙ 1 - Initialize and load, if not already loaded, signal processor for play operations. ∙ 2 - Initialize and load, if not already loaded, signal processor for record operations. ∙ 3 - Initialize and load, if not already loaded, signal processor for monitor operations. 3. SEEKTYPE - Type of processing to do on the audio objects. ∙ 0 - Initialize for audio objects in passed FAB. Seek to position requested in "AUDSTART". ∙ 1 - Seek to position requested in "AUDSTART" in current audio object(s). ∙ 2 - Continue in the current audio object(s) with no seek. ∙ 3 - Release audio object resources allocated by AAPI. No other processing is done. Assumes FAB information is still correct. ∙ 4 - End processing on current audio object(s), and initialize for audio objects in passed FAB. Seek to position requested in "AUDSTART". Assumes that previous FAB is still allocated and valid. 4. AUDTYPE - Type of compression method to use when recording, or moni- toring. ∙ 00h - Use method in current object, or default for new object ∙ 01h - Use ADPCM/11K algorithm (mono music) ∙ 02h - Use ADPCM/5.5K algorithm (mono voice) ∙ 03h - Use ADPCM/22K algorithm (stereo music) ∙ 04h - Use ADPCM/22K algorithm (mono high quality music) | ∙ 60h - Use PCM algorithm 5. INTLEVEL - The hardware interrupt level the audio card has been con- figured to use. 6. INPSRCE - The input source the audio card should consider active. 4. Control Data Structures 42 ∙ 00h - Microphone input - normal gain ∙ 01h - Line level input - left channel only ∙ 02h - Line level input - right channel only ∙ 03h - Line level input - both channels ∙ 04h - Microphone input - low gain 7. PIOBASE - The starting address of a block of eight I/O addresses that the audio card has been configured to use. 8. CONTROLS - flag indicating control changes to execute ∙ 01h - Set the master volume based on caller's input ∙ 02h - Set the track volume based on caller's input ∙ 04h - Set the track volume (at a different position) ∙ 08h - Set the channel balance based on caller's input ∙ 10h - Set the position in the audio to stop current operation ∙ 20h - Refresh the I/O buffer if necessary ∙ 40h - Pause the current operation until a "resume" control is requested. ∙ 80h - Resume a "paused" operation. 9. OPRPARMS - flag indicating parameters for DSP operations. ∙ 02h - Do not update audio and volume object segment totals during record operations. The variable sections of these objects will be updated normally but fields in the header will not be changed by the AAPI. ∙ 04h - Enables the PS/2 speaker for output from the audio card. This has no effect on the other output sources (line, speaker). This flag is ignored if not running on a PS/2 system. ∙ 10h - Enables pass through of any input to the card, while recording, to the output channels, before any compression is done. ∙ 20h - Enables pass through of any input to the card, while recording, to the output channels, after compression has taken place. ∙ 200h - If the process that the Audio API is running in is switched to the background (user task switch for example) the current oper- ation will be cancelled and an error will be returned to the caller (OS2 only). 4. Control Data Structures 43 ∙ 400h - If playing VOICE mode audio is requested first, then setting this flag will cause the DSP code environment to be set up to play VOICE and MIDI simultaneously. If the flag is not set then the DSP environment will be set up for VOICE and (VOICE or MUSIC). 10. FILEPTR - A pointer to a File Access Block for an audio file. This pointer allows access, using FABOs, to the various audio objects. 11. SUBTYPE - The sub-type of the objects to operate on. This would normally be zero if only one track of audio data is in the file. 12. AUDSTART - The start position in milliseconds of where to begin the requested operation in the audio track. A value of zero will be con- sidered the physical start of the track. 13. AUDEND - The end position in milliseconds of where to stop the requested operation in the audio track. A value of zero will be con- sidered the physical end of the track. 14. BUFFLEN - The length of the caller passed I/O buffer (buffptr), or the length that the AAPI should allocate from main memory. 15. BUFFPTR - A pointer to a buffer to be used for I/O operations by the AAPI. 16. EMMHAN - The extended memory manager handle to use if the caller passes a LIM memory pointer (BUFFPTR). 17. EMMCNT - The extended memory manager page count to use if the caller passes a LIM memory pointer (BUFFPTR). 18. MEMID - The type of memory passed by the caller in "BUFFPTR". ∙ 00h - not allocated ∙ 01h - main memory ∙ 02h - LIM memory ∙ 03h - Device 19. RESERVED - A reserved area for additional information about the call- er's passed memory area. 20. CTLPARMS - flag indicating parameters for control requests ∙ 01h - Stop request will ignore other controls in progress or pending and execute at the time requested in STOPPOS. If the bit is off the stop will not execute until the time requested (STOPPOS) and all other controls in progress or pending have com- pleted. 4. Control Data Structures 44 ∙ 02h - Purge this channel's control queue before processing any new controls requested in CONTROLS. ∙ 04h - This call is being made from within an interrupt service routine in DOS. The call will not be processed if DOS is "busy" and not re-entrant. ∙ 08h - Based on what "CONTROLS" value is set (pause or resume) the current operation for all channels will be paused or resumed if this flag is set. If the flag is not set then only the current channel will be affected. | ∙ 10h - Requests that any previously saved control information be | restored. This is used to restart a play or record operation in | the same position with the same control settings as when it was | stopped. 21. MASVOL - For ADPCM, a value from zero to one hundred specifying the percentage of maximum volume that can be used at this time. For example, a setting of 70 would mean that only 70% of the maximum | volume the hardware supports will be allowed. When playing and | recording PCM the upper limit is 120%. Setting values over 100% cause | the volume level of the track being recorded or played to be boosted | above its original recorded level. 22. TRKVOL1 - A value from zero to one hundred specifying the percentage of the maximum volume to be used while playing this track. The maximum volume allowed is based on what the hardware can support and the current setting of the master volume (MASVOL) control. 23. TRKVOL1S - The start position in milliseconds of where to begin fading the track volume level (TRKVOL1) in the audio track. 24. TRKVOL1E - The end position in milliseconds of where to complete the track volume level change in the audio track. Subtracting TRKVOL1S from TRKVOL1E will give the amount of time in milliseconds that will be used while fading from the current track volume setting to the requested volume setting (TRKVOL1). 25. TRKVOL2 - A value from zero to one hundred specifying the percentage of the maximum volume to be used while playing this track. The maximum volume allowed is based on what the hardware can support and the current setting of the master volume (MASVOL) control. 26. TRKVOL2S - The start position in milliseconds of where to begin fading the track volume level (TRKVOL2) in the audio track. 27. TRKVOL2E - The end position in milliseconds of where to complete the track volume level change in the audio track. Subtracting TRKVOL2S from TRKVOL2E will give the amount of time in milliseconds that will be used while fading from the current track volume setting to the requested volume setting (TRKVOL2). 4. Control Data Structures 45 28. CHNBAL - A value from zero to one hundred specifying the percentage of the signal balance that is sent to the first channel in the two channels named in "OUTCHN". The second channel receives the remainder of the signal. 29. OUTCHAN - A value that indicates the pair of channels that "CHNBAL" is dividing the signal between. ∙ 00h - Left channel(signal % in CHNBAL), Right channel (remaining %) ∙ 01h - Right channel (signal % in CHNBAL), Left channel (remaining %) 30. CHNBALS - The start position in milliseconds in the audio track of where to begin fading from the current balance setting to the requested balance setting (CHNBAL). 31. CHNBALE - The end position in milliseconds in the audio track of where to complete fading from the current balance setting to the requested balance setting (CHNBAL). 32. STOPPOS - The position in milliseconds in the audio track of where to stop the current operation. 33. IOTIME - The amount of audio data (in milliseconds) that the caller is requesting to be read into or written from the I/O buffer (BUFFPTR). A zero value will cause the maximum amount of data possible to be read or written. 34. ACB2PTR - A pointer to a second Audio Control Block. The AAPI will attempt to perform the requested operations in both ACBs as simultane- ously as possible. This field allows two channel play and dub oper- ations to be done with one call. The return code for the second ACB is in the output field "ACB2RC". 35. LISTPTR - A pointer to a structure (linked list) of start/stop posi- tions to use during play operations. This list is used after the position in "AUDEND" is reached. 36. DSP_PATH - A pointer to a directory path to use to find the signal processor code files. If this field is zero then the current direc- tory is used. | 37. SVRSPTR - A pointer to a save/restore area to be used to store the | current control state (volume, balance, etc). | | 38. FMTPTR - A pointer to a audio format area containing information about | the type of audio compression being performed. 39. IN_RESERVE - A 20 byte area reserved for expansion of the input param- eters. 4. Control Data Structures 46 40. POSITION - The current position (in milliseconds) in the audio data. This field is updated at .1 second intervals by the AAPI during asyn- chronous audio operations. 41. STATE - The current state of the signal processor. ∙ 00h - Stopped. The signal processor is halted. ∙ 01h - Playing. The signal processor is playing. ∙ 02h - Recording. The signal processor is recording. ∙ 03h - Stopping. The signal processor has received a stop request but is completing an operation before stopping. 42. BACKRC - Return code set by the AAPI when running in the background. After an operation has been started, and the AAPI detects an error (device full for example), the operation will be stopped and this field will contain the error code. 43. ACB2RC - The return code from a second ACB passed in field "ACB2PTR". 44. TIMELEFT - Time remaining before the AAPI begins asynchronous I/O. 45. OUPDATES - Audio objects updated flag ∙ 01h = AUDIO object changed ∙ 02h = VOLUME object changed ∙ 04h = ESCAPE object changed 46. OUT_RESERVE - An eight byte area reserved for expansion of the output parameters. 47. AAPIWORK - A reserved area for the AAPI work area. | 4.4 AUDIO FORMAT STRUCTURE (AFMT) ___________________________________ | The AFMT is the structure used to pass additional information about the | audio type. Currently it is only used with the PCM audio type. The field | values marked below with (W) are valid for RIFF WAVE files. If the caller | uses other values (marked with (i)) that are valid in the AAPI but not yet | defined for the RIFF WAVE format then the file will be saved as a RIFF | file but with a form type of "ibmw" instead of WAVE. 4. Control Data Structures 47 | ; ** Audio Format Structure | ; _________________________ | afmt struc | ; | format dw ; Format of audio data | ; 01h = Linear PCM (W) | ; 02h = mu-law (W) | ; 03h = A-law (W) | samples_per_second dd ; Sample rate in hertz | ; 8000, 11025, 22050, 44100 (W) | bits_per_sample dw ; Sample width in bits | ; 8 or 16 (W) | channels dw ; Number of channels | ; 1 or 2 (W) | sample_number_format dw ; Format of sample | ; 02h = Unsigned (W) | ; (8 bits per sample) | ; 01h = Signed | ; 00h = 2's complement (W) | ; (16 bits per sample) | dither_percent dw ; Amount of dither in % of | ; one bit (Rec/monitor only) | ; 21h = Recommended value | format_flag dw ; General flag | ; 01h - Source Mix on | reserved db 20 dup ; Reserved for expansion | afmt ends | | See Appendix C, "Additional Information on PCM Support" on page 71 for a | detailed explanation of the above fields. 4. Control Data Structures 48 5. USAGE EXAMPLES __________________ 5.1 CHECK AUDIO HARDWARE AND SOFTWARE CONFIGURATION ____________________________________________________ 1. Verify that signal processor microcode file is located in a path that can be found when the application is executed. 2. Allocate an Audio Device Control Block to pass to the AAPI. 3. Call AUD_CFIG passing a pointer to the ADCB. 4. Check return code ∙ If 0, this system has an available audio device. The ADCB con- tains the hardware configuration information. ∙ If 3224, no audio device was found. ∙ If 3225, an audio device was found, but interrupts are disabled. ∙ If 3226, the system has an audio device, but the device driver is not responding. The OS/2 error code is available in the ADCB. 5.2 PLAY (SINGLE CHANNEL) __________________________ | 1. Determine type of audio file (FAB_TYPE). 2. Allocate and initialize FAB/FABOs and open the audio file (FAB_OPEN, FAB_ROPN, or application file handling code) 3. Allocate an I/O buffer and an ACB to pass to the AAPI. 4. Call AUD_INIT passing the ACB pointer. 5. Call AUD_SET with the appropriate parameters. These parameters can include setting volume fade-in and fade-out controls and the position in the audio to stop playing. 6. Call AUD_STRT when ready to start playing. Monitor the following output fields in the ACB which will be updated at .1 second intervals: ∙ POSITION - Current position in audio. ∙ TIMELEFT - Time left before AAPI will begin doing asynchronous I/O to refill the audio buffers. 7. Call AUD_CTRL* as many times as necessary to change audio controls and/or to request that I/O be performed to refill the audio buffers. 5. Usage Examples 49 8. Call AUD_SET to continue or start a new operation or AUD_TERM to ter- minate audio processing. If AUD_TERM is called all audio objects that were not already open before the AUD_INIT call will be closed. * Note: Audio control requests can be made on all AAPI calls except AUD_INIT and AUD_TERM by setting the "CONTROLS" parameter in the ACB. 5.3 RECORD/MONITOR ___________________ | 1. Determine type of audio file (FAB_TYPE). 2. Allocate and initialize FAB/FABOs and open the audio file (FAB_OPEN, FAB_ROPN or application file handling code) 3. Allocate an I/O buffer and an ACB to pass to the AAPI. 4. Call AUD_INIT passing the ACB pointer. 5. Call AUD_SET with the appropriate parameters. 6. Call AUD_STRT when ready to start recording. Monitor the following output fields in the ACB which will be updated at .1 second intervals: ∙ POSITION - Current position in audio. ∙ TIMELEFT - Time left before AAPI will begin doing asynchronous I/O to flush the audio buffers. 7. Call AUD_CTRL as many times as necessary to request that I/O be per- formed to flush the audio buffers or to set the stop point in the audio. 8. Call AUD_SET to continue or start a new operation or AUD_TERM to ter- minate audio processing. If AUD_TERM is called all audio objects that were not already open before the AUD_INIT call will be closed. 5.4 PLAY (TWO CHANNEL) _______________________ Method 1 - Use the single channel example above for both channels. The caller must do a separate call for each channel for all requests. Method 2 - Pass a secondary ACB | 1. Determine type of audio file for each channel (FAB_TYPE). 2. Allocate a FAB and open an audio file (FAB_OPEN, FAB_ROPN) for each channel. 3. Allocate an I/O buffer and an ACB for each channel. 5. Usage Examples 50 4. Call AUD_INIT passing the ACB pointer and the second ACB pointer in ACB2PTR. Both ACBs will be initialized. 5. Set the appropriate parameters in both ACBs and call AUD_SET. 6. Call AUD_STRT when ready to start playing. Monitor the following output fields in the ACB(s) which will be updated at .1 second intervals: ∙ POSITION - Current position in audio. ∙ TIMELEFT - Time left before AAPI will begin doing asynchronous I/O to refill the audio buffers. 7. Call AUD_CTRL* as many times as necessary to change audio controls and/or to request that I/O be performed to refill the audio buffers. 8. Call AUD_SET to continue or start a new operation or AUD_TERM to ter- minate audio processing. If AUD_TERM is called all audio objects that were not already open before the AUD_INIT call will be closed. * Note: Audio control requests can be made on all AAPI calls except AUD_INIT and AUD_TERM by setting the "CONTROLS" parameter in the ACB. 5. Usage Examples 51 6. AVC AUDIO FILE FORMAT _________________________ 6.1 AUDIO FILE OVERVIEW ________________________ The following section provides an overview of the AVC file structure that is used by the AAPI. Detailed descriptions of the data structures that make up these files is presented in 6.2, "File Data Structures" on page 55. 6.1.1 AUDIO FILE TYPES There are two types of files associated with a piece of AVC audio. An "AUDIO" file and an "ESCAPE" file. Together, these files make up a single entity that can be created, opened, and manipulated. This document, when discussing an "audio file" will always mean the "AUDIO" file. When refer- ring to the "ESCAPE" file, "escape file" will always be used. 6.1.1.1 "AUDIO" File The "AUDIO" file contains general information about the file itself and sub-components called "objects". The file contains a header and a vari- able length internal directory locating the objects. The header contains information necessary to verify that it is an audio file, read the internal directory, and recreate external directories to the objects within the file. Each directory entry identifies an object, its size, and its location within the file. 6.1.1.2 "ESCAPE" FILE The "ESCAPE" file contains digitized audio data. All information about the data and how to access it are contained in objects in the audio file. 6.1.2 AUDIO OBJECT TYPES Each object has a distinct type code. The type code identifies its par- ticular format. An object can also be further distinguished by a sub-type field which indicates further differences as to usages by an application. The sub-type field also distinguishes between multiple objects of the same type in the same file. Each object consists of a header and data section. The header has the same data structure for all objects of the same type and provides suffi- cient information to process the data section. An audio file does not necessarily contain all objects, only the "Audio", "Escape", and "Volume" objects are required. The objects may appear in any order in the file. 6. AVC Audio File Format 52 There are five types of audio objects. Figure 1 on page 54 shows the structure and relationships of the audio files and objects. A brief description of each object type and how it is used by the AAPI is given below. "AUDIO" Object The "AUDIO" object is a standard object that contains general information about, and an index to, a collection of digitized audio data. The "unique to object" section includes the following information about the audio data: ∙ Length of data (milliseconds and bytes) ∙ Encoding scheme ∙ Indexing scheme The "variable section" includes the following information about the audio data: ∙ Array of indexes into audio data. Each index points to an audio segment. An audio segment is an addressable unit of audio. The AAPI uses this object to locate and read audio data for playing, and updates this object during record. "AUDVOL" Object The "AUDVOL" object is a standard object that contains volume information. This volume information corresponds to the indexed segment information in the "AUDIO" object. Each indexed segment has a corresponding volume entry. The "unique to object" section includes the following information about the audio data: ∙ Number of volume data entries. The "variable section" includes the following information about the audio data: ∙ Volume information about one segment of audio data The AAPI updates this object during record operations. "ESCAPE" Object The "ESCAPE" object is a special type of object that has normal header sections but no variable section. The "ESCAPE" object points to a sepa- rate "escape" file. The contents of this file is the digitized audio data. 6. AVC Audio File Format 53 ┌────────────────────────────────────────────────────────────────────────┐ │ │ │ AUDIO File │ │ │ │ │ │ │ │ │ "AUDIO" Object │ │ │ │ │ │ General information about audio data │ │ │ Index to individual audio segments │ │ │ (one index entry for each segment) │ │ │ │ │ │ "AUDVOL" Object │ │ │ │ │ │ Volume data for audio segments │ │ │ (one volume entry for each audio segment) │ │ │ │ │ │ "ESCAPE" Object │ │ │ │ │ │ Information about separate "escape" file │ │ │ │ │ │ "AUDPNTS" Object │ │ │ │ │ │ Application program information │ │ │ │ │ │ "AUDLABL" Object │ │ │ │ │ │ Application program information │ │ │ │ │ End of AUDIO File │ │ │ │ │ │ │ │ ESCAPE File │ │ │ │ │ │ Digital audio data segments │ │ │ │ │ End of ESCAPE File │ │ │ └────────────────────────────────────────────────────────────────────────┘ Figure 1. Audio Files and Objects The "unique to object" section includes the following information about the audio data: ∙ "Escape" file access information The "variable section" includes the following information: ∙ None The AAPI reads this data during play, and updates this object during record. 6. AVC Audio File Format 54 "AUDPNTS" Object The "AUDPNTS" object is a standard object that contains application infor- mation about the audio data. The "unique to object" section includes the following information about specific points in the audio. ∙ Number of points listed in variable section The "variable section" includes the following information about the audio data: ∙ Point position (milliseconds) ∙ Application information The AAPI does not use this object but will allocate and initialize it if requested. "AUDLABL" Object The "AUDLABL" object is a standard object that contains a subset of the information in "AUDPNTS" object. The "unique to object" section includes the following information about specific points in the audio. ∙ Number of points listed in variable section The "variable section" includes the following information about the audio data: ∙ Point position (milliseconds) ∙ Application information The AAPI does not use this object but will allocate and initialize it if requested. 6.2 FILE DATA STRUCTURES _________________________ The following section provides detailed information on the data structures needed to create and manipulate audio files both on disk and in memory. The AAPI provides functions to perform high level file processing using these structures, but the caller must still have an understanding of the structures to do more complicated operations. The caller need not use the AAPI file functions at all, replacing them with his own, as long as the file data is kept in the correct format when presented to the AAPI. 6. AVC Audio File Format 55 6.2.1 DIRECTORY CONTROL BLOCK This is a representation of the organization of an audio file on disk. It consists of a header and an array of directory entries, each entry repres- enting an object in the file. The overall directory control block is: Directory Control Block Directory header First directory entry Next directory entry . . Last directory entry End of Directory Control Block ; ** Directory Control Block Header ** ; _________________________ dcbh struc ; sig db 8 dup ; Signature and null terminator vers dw ; Version/Modification ftype dw ; File type eod dd ; Total bytes of data reserve1 dd ; Reserved - compatibility ents dw ; Number of directory entries activ dw ; Number of active directory entries reserve2 db 12 dup ; Reserved - compatibility name db 64 ; ASCII-z reference code reserve3 db 36 dup ; Reserved - compatibility reserve4 db 21 dup ; Reserved - expansion reserve5 db 3 dup ; Reserved - compatibility dcbh ends The fields in the Directory Control Block Header are defined below. Any field where specific values are not given should be set to zero for com- patibility with other products. Likewise, any reserved fields should be set to zero. 1. SIG - A standard literal string identifying the file for a particular product. The signature for the AVC product is "+A+V+C+". 2. VERS - Indicates the level of the file, permitting recognition and processing of down-level files. 3. FTYPE - A code to characterize the file in general terms. Audio files shoud be set to 0x0500. 4. EOD - Total bytes is the data area spanned by the file from the begin- ning of the directory to the end of the physically last object. The offset following the end of this last object is available for writes of new or updated objects. 6. AVC Audio File Format 56 5. RESERVE1 - Reserved for product compatibility. 6. ENTS - Number of directory entries is a count enabling functions opening a file to allocate the proper amount of memory to hold the entire directory. Null directory entries, if any, are included in this count. 7. ACTIV - Number of active directory entries is a count of the non-null entries. Active entries physically appear first in the directory. 8. RESERVE2 - Reserved for product compatibility. 9. NAME - Fully-qualified file name. 10. RESERVE3 - Reserved for product compatibility. 11. RESERVE4 - A reserved area for future expansion. 12. RESERVE5 - Reserved for product compatibility. ; ** Directory Control Block Entry ** ; _________________________ dcbe struc ; type dw ; Object type code subtype dw ; Object subtype code reserve1 db 2 dup ; Reserved - compatibility sizh dw ; Size of object header in file sizv dd ; Size of data section in file size dd ; Size of object in file reserve2 db 4 dup ; Reserved - compatibility offset dd ; Objects offset in file reserve3 db 8 dup ; Reserved- expansion dcbe ends The fields in the Directory Control Block Entry are defined below. Any field where specific values are not given should be set to zero for com- patibility with other products. Likewise, any reserved fields should be set to zero. 1. TYPE - Classifies the object and indicates the layout of the object's header. The object type and sub-type codes for a null entry are 0000. See the FAB type field for valid audio object types. 2. SUBTYPE - See the FAB subtype field for valid audio object subtypes. 3. RESERVE1 - A reserved area for product compatibility. 4. SIZH - Number of data bytes in the file for the header section. 5. SIZV - Number of data bytes in the file for the data section. 6. SIZE - Total number of bytes for both the header and data section. 6. AVC Audio File Format 57 7. RESERVE2 - A reserved area for product compatibility. 8. OFFSET - The object's offset from the start of the file. 9. RESERVE3 - A reserved area for future expansion. 6. AVC Audio File Format 58 6.2.2 FILE ACCESS BLOCK (FAB) This is the representation of an audio file in memory. It has a header and immediately following, a list of file objects -- referred to as the FABO list. Unlike the directory, however, the FABO list does not neces- sarily identify all objects in the file; it only contains those of interest to the application. The overall directory control block is: File Access Block File Access Block Header FABO - first object FABO - next object . . FABO - last object End of File Access Block ; ** File Access Block Header ** ; _________________________ fabh struc ; fabbit dw ; FAB status flag fabcnt dw ; Number of FABO'S in FABO list fabhdl dw ; File handle fabver dw ; Version/modification number reserve1 db 2 dup ; Reserved - compatibility fabtyp dw ; File type reserve2 db 10 dup ; Reserved - compatibility fabnam db 64 dup ; ASCII-z file name reserve3 db 8 dup ; Reserved- expansion fabstat dw ; FAB commit flag fabh ends The fields in the File Access Block Header are defined below. Any field where specific values are not given should be set to zero for compat- ibility with other products. Likewise, any reserved fields should be set to zero. The fields in the File Access Block Header can have the following values: 1. FABBIT - Status flags - None currently defined 2. FABCNT - Number of FABO's is a count of elements in the FABO array. 3. FABHDL - Operating system file handle for audio file. 4. FABVER - Equivalent to the directory version number. 5. RESERVE1 - A reserved area for product compatibility. 6. FABTYP - The following types are valid: 6. AVC Audio File Format 59 ∙ Audio File - 0x0500 7. RESERVE2 - A reserved area for product compatibility. 8. FABNAM - ASCII-z reference string (name of file) 9. RESERVE3 - A reserved area for future expansion. 10. FABSTAT - 0x0080 - FAB has been committed ; ** File Access Block Object ** ; _________________________ fabo struc ; fostat dw ; Object status flags 0x0001 = Data section modified 0x0002 = Data section in memory 0x0010 = Header section modified 0x0020 = Header section is in memory 0x0080 = Object is on disk 0x0100 = Data section is allocated 0x0200 = Header section is allocated 0x2000 = Escape file open fotype dw ; Object type code fosub dw ; Object subtype fosizh dw ; Size of header section fosizv dd ; Size of data section reserve1 db 5 dup ; Reserved - compatibility fohdptr dd ; Pointer to header section fabo ends The fields in the File Access Block Object are defined below. Any field where specific values are not given should be set to zero for compat- ibility with other products. Likewise, any reserved fields should be set to zero. 1. FOSTAT - Process and error flags. See above for bit values. 2. FOTYPE - The following types are valid: ∙ Audio - 0x0500 ∙ Volume - 0x0501 ∙ Points - 0x0502 ∙ Labels - 0x0503 ∙ Escape - 0x8500 3. FOSUB- Object subtype is the same as the directory entry. 6. AVC Audio File Format 60 4. FOSIZH - Size of the header in memory is always 16 bytes larger than the size on disk, since the memory header contains memory location information about the data piece of the object. 5. FOSIZV - Size of the data section. 6. RESERVE1 - A reserved area for product compatibility. 7. FOHDPTR - A pointer to the header section. The header in memory in turn contains a pointer to the data section. 6. AVC Audio File Format 61 6.2.3 AUDIO OBJECTS Each object consists of a header and data section. All objects of a par- ticular type have the same header size and layout. Among objects of the same type, data sections tend to differ from one another is size, though not in general structure. An object's header has three parts, the first two which are common to all objects, no matter what the object type. The first is a set of run_time fields with memory location information for the object's data section; these fields exist only in the memory representation of the object and are not saved on disk. The second part is a standard prologue whose principal use is to assist in finding the object in memory or file dumps. The rest of the header is data unique to the particular object type. The overall layout of an object header is: Object Header Common memory section Common prologue Unique to object section End of Object Header ; ** Object Header Common Memory ** ; _________________________ obmem struc ; dataptr dd ; Pointer to start of data section | reserve1 db 26 dup ; Reserved - expansion | mem_id dw ; Memory type ; 0x00 = Not allocated ; 0x01 = Main memory ; 0x02 = LIM memory ; 0x03 = Device fabh ends The fields in the Object Header Common Memory section are defined below. Any field where specific values are not given should be set to zero for compatibility with other products. Likewise, any reserved fields should be set to zero. 1. DATAPTR - The address of the data section of the object. 2. RESERVE1 - A reserved area for expansion 3. MEM_ID - Type of memory for data section. See above for types. 6. AVC Audio File Format 62 ; ** Object Header Common Prologue ** ; _________________________ obmem struc ; obj_ids db 8 dup ; Visual ID and null terminator obj_ver dw ; Version cmp_typ dw ; Compression type reserve1 db 4 dup ; Reserved fabh ends The fields in the Object Header Common Prologue are defined below. Any field where specific values are not given should be set to zero for com- patibility with other products. Likewise, any reserved fields should be set to zero. 1. OBJ_ID - A seven character literal string that identifies a particular object type. The following IDs are valid: ∙ Audio Object - "AUDIO " ∙ Volume Object - "AUDVOL " ∙ Points Object - "AUDPNTS" ∙ Labels Object - "AUDLABL" ∙ Escape Object - "ESCAPE " 2. OBJ_VER - Indicates the level of the object, permitting functions to recognize and possibly process down_level formats. 3. CMP_TYPE - A code applicable to objects whose data section is stored in compressed form in the file. It indicates a particular compression algorithm. 4. RESERVE1 - A reserved area for expansion. 6.2.3.1 Object Descriptions The unique header fields and data sections are different for each object and are described below. AUDIO OBJECT DESCRIPTION: The audio header occupies 64 bytes in a file and 80 in memory. 6. AVC Audio File Format 63 ; ** Audio Object Header Structure ** ; _________________________ audobjh struc ; com_mem db 32 dup ; Common memory structure com_pro db 16 dup ; Common prologue structure aud_time dd ; Length of audio in milliseconds aud_end dd ; Offset to end of segment data aud_segm dw ; Length of segment in milliseconds aud_segb dw ; Length of segment in bytes aud_dion dw ; # of segment index entries aud_dil dw ; Length of a segment index entry (bytes) aud_blks dw ; Total number of physical segments aud_grb dw ; Total number of garbage segments aud_fg1 db ; Format flag ; 0x80 = Fragmented ; 0x40 = Sequential ; 0x20 = Silence segment at start of ; escape file aud_fg2 db ; Coding type ; 0x80 = Fixed rate coding ; 0x40 = Variable rate coding ; 0x20 = Variable segment size ; 0x10 = Variable segment time aud_comp dw ; Compression method ; 0x00 = Default - ADPCM/11K ; 0x01 = ADPCM 11.0K (mono) ; 0x02 = ADPCM 5.5K (mono) ; 0x03 = ADPCM 22.0K (stereo) ; 0x04 = ADPCM 22.0K (mono) ; 0x64 = AVC MIDI aud_mcid dw ; Microcode ID ; 0x00 = Pre-release version ; 0x01 = Post-release (V1.02 and up) reserve1 db 22 dup ; Reserved audobjh ends An audio object's data section is a simple continuous array of 3-byte offsets to the digital audio, based on the premise of fixed rate coding. The index entry size allows for 24 minutes of audio when digitizing at 11k bytes per second. ; ** Audio Object Data Structure ** ; _________________________ audobjd struc ; aud_dof db 3 dup ; Offset to digital data segment audobjd ends VOLUME OBJECT DESCRIPTION: The audio header occupies 32 bytes in a file and 48 in memory. 6. AVC Audio File Format 64 ; ** Volume Object Header Structure ** ; _________________________ volobjh struc ; com_mem db 32 dup ; Common memory structure com_pro db 16 dup ; Common prologue structure aud_voln dw ; # of volume data entries reserve1 db 14 dup ; Reserved for expansion volobjh ends A volume object's data section is a simple array of 1-byte volume codes. ; ** Audio Object Data Structure ** ; _________________________ volobjd struc ; aud_vol db ; Volume data ; Stereo - Left Nibble = Left track ; Right Nibble = Right track ; Mono - Right Nibble = Valid ; Left Nibble = Undefined ; Sum of ; bits 0,1,2 / Input RMS Voltage ; 0 / 0 ; 1-3 / .001 - .06 ; 4 / .06 - .12 ; 5 / .12 - .24 ; 6 / .24 - .47 ; 7 / .47 - 2.4 ; Bit 3 ; On = Clipping occurred volobjd ends POINTS OBJECT DESCRIPTION: The points header occupies 32 bytes in a file and 48 in memory. ; ** Points Object Header Structure ** ; _________________________ pntobjh struc ; com_mem db 32 dup ; Common memory structure com_pro db 16 dup ; Common prologue structure aud_plon dw ; Number of point list entries reserve1 db 14 dup ; Reserved for expansion pntobjh ends A point object's data section is an array of 76-byte audio points 6. AVC Audio File Format 65 ; ** Audio Points Data Structure ** ; _________________________ pntobjd struc ; aud_ptm dd ; Point position in time (milliseconds) aud_plb db 6 dup ; Label for point - ASCII-z aud_pcm db 41 dup ; User annotation of point - ASCII-z aud_ppc db 8 dup ; Mix program - command - ASCII-z aud_ppl db 5 dup ; Mix program - level - ASCII-z aud_ppt db 5 dup ; Mix program - time - ASCII-z aud_pfl db ; Point flag reserve1 db 6 dup ; Reserved for expansion pntobjd ends LABELS OBJECT DESCRIPTION: The labels header occupies 32 bytes in a file and 48 in memory. ; ** Labels Object Header Structure ** ; _________________________ labobjh struc ; com_mem db 32 dup ; Common memory structure com_pro db 16 dup ; Common prologue structure aud_lbln dw ; Number of labels entries reserve1 db 14 dup ; Reserved for expansion labobjh ends A point object's data section is an array of 12-byte audio labels ; ** Audio Points Data Structure ** ; _________________________ pntobjd struc ; aud_ltm dd ; Point position in time (milliseconds) aud_lbl db 6 dup ; Label for point - ASCII-z reserve1 db 2 dup ; Reserved for expansion ESCAPE FILE REFERENCE OBJECT DESCRIPTION: An escape file contains data which is too big and unwieldy to be handled within a normal data section of an object. The escape file is associated with an audio file, and the audio file contains an "escape file reference object" to describe the sep- arate escape file. An escape file reference object has only a header; there is no data section (this is the data in the escape file). The header occupies 112 bytes in the file and 128 in memory. 6. AVC Audio File Format 66 ; ** Escape File Reference Object Header Structure ** ; _________________________ escobjh struc ; com_mem db 32 dup ; Common memory structure com_pro db 16 dup ; Common prologue structure reserve1 db 2 dup ; Reserved - compatibility esc_sig dw ; Signature flag ; 0x00 = Standard signature ; 0x01 = No signature reserve2 db 8 dup ; Reserved - compatibility esc_ref db 64 dup ; ASCII-z name of escape file esc_hdl dw ; Escape file handle esc_thl dw ; Temporary escape file handle reserve3 db 16 dup ; Reserved for expansion escobjh ends The first 32 bytes of the escape file is a file signature with the fol- lowing layout: ; ** Escape File Signature Structure ** ; _________________________ escsgnh struc ; sgn_sgn db 8 dup ; ASCII-z signature ; AVC = "+A+V+C+" sgn_ver dw ; Version modification sgn_type dw ; File type ; 0x8000 = Escape file reserve1 db 8 dup ; Reserved - compatibility reserved db 12 dup ; Reserved - expansion escsgnh ends 6. AVC Audio File Format 67 7. RIFF WAVE AUDIO FILE FORMAT _______________________________ 7.1 AUDIO FILE OVERVIEW ________________________ The AAPI supports the Microsoft Resource Interchange File Format (RIFF) Waveform Audio File Format (WAVE). Users should refer to the Microsoft Multimedia Development Kit for details of this format. The AAPI supports the Microsoft Resource Interchange File Format (RIFF) Waveform Audio File Format (WAVE). Users should refer to the Microsoft Multimedia Development Kit for details of this format. If the AAPI file level functions (FAB_TYPE, FAB_ROPN, FAB_SAVE, FAB_CLOSE) are used then detailed knowledge of the RIFF WAVE format should not be necessary. Once RIFF WAVE files have been read into memory they are represented using the AVC file format structures so that the AAPI audio control functions can work transparently on both types of files. 7. RIFF WAVE Audio File Format 68 APPENDIX A. OS/2 CONSIDERATIONS ________________________________ A.1 OS/2 USAGE ________________ The OS/2 version of the AAPI is shipped as a dynamic link library (DLL) and an accompanying import library. The user statically links the appli- cation with the import library and then places the DLL somewhere in the operating system's DLL path. All calls to the DLL must be far calls and all pointers passed must be far data pointers. A.2 OS/2 DEVICE DRIVER ________________________ When running an application using the AAPI under OS/2 the following state- ments must be added to the CONFIG.SYS file: DEVICE=\Your_Device_Path\M-ACPA_OS/2_Device_Driver_Name IOPL=YES The device driver must be installed even if the DOS version of the AAPI is being used in the DOS Compatibility box. The compatibility device driver for AVC must be installed if the AAPI application is going to be used in OS/2 or any other application other than the AAPI is going to access the M-ACPA card. If AAPI applications only are going to be run in the DOS box then the minimal device driver may be used. See the M-ACPA Device Driver document for more details. Appendix A. OS/2 Considerations 69 APPENDIX B. DOS CONSIDERATIONS _______________________________ B.1 DOS USAGE _______________ In DOS the AAPI is delivered as a large model C library that should be statically linked with the application. The AAPI routines were compiled using the Microsoft C 6.00 Compiler. B.2 DOS DEVICE DRIVER _______________________ When running an application using the AAPI under DOS the following state- ment must be added to the CONFIG.SYS file: DEVICE = \Your_Device_path\M-ACPA_DOS_Device_Driver_Name The minimal or full function M_ACPA driver may be used. If no other audio applications are using the M_ACPA then use the minimal driver. If more than one application other than AAPI applications may be using the M_ACPA then use the full function device driver. See the M-ACPA Device Driver documentation for more details. B.3 DOS REENTRANCY ____________________ Using the Audio API under DOS will result in the Audio API interrupt handler being invoked at random times. Since DOS is not reentrant, the interrupt handler checks the DOS critical section flag before using any DOS services (such as for disk I/O). The AAPI caller should not structure the application program in a way that leaves this critical section flag on for long periods of time. This will prevent the interrupt handler from using DOS services. For example, using DOS calls in a very tight loop to poll the user for input could cause this situation. B.4 EXPANDED MEMORY _____________________ If expanded memory is being used, the LIM device driver must meet certain performance requirements and be re-entrant for the AAPI to perform ade- quately. All device drivers we have tested have been acceptable with the exception of the DOS 4.0 XMAEMS/XMAEM combination on 386 machines. XMAEMS on 286 machines does have acceptable performance. Appendix B. DOS Considerations 70 APPENDIX C. ADDITIONAL INFORMATION ON PCM SUPPORT __________________________________________________ C.1 SIGNIFICANCE OF THE DIFFERENT PCM MODES ____________________________________________ PCM or Pulse Code Modulation is a method of encoding sound information as a series of numerical sound samples. The current PCM support allows the user to record and play data at a variety of sample widths and sample rates. The choice of which sample rate and width to use is essentially an economic trade-off between storage size and sound quality. C.1.1 SAMPLE RATE The choice of sample rate determines the highest frequency which can be represented by the sampled sound data. Consider the problem of sampling a relatively low frequency sound signal: Low Frequency Sound ------------------- * * * * | * * | | * * | | * * | | * * | | * *| | | * * | | | * * | | | |* * | | | | | | | | | V V V V Sound Samples Clearly the low frequency sound pictured above can be represented nicely if we take samples at the regular rate shown. What about a higher fre- quency sound? Appendix C. Additional Information on PCM Support 71 High Frequency Sound -------------------- * * * * * * * * * * * * * | * |* * * * * * * * | | * | * * |* * * * * * | | | | * * | * * |* * * * | | | | | * * | * * | * * |* * | * | * | * | * V V V V Sound Samples Clearly the higher frequency sound shown above can not be represented by samples taken at the rate shown. The low points of the signal between each sample would be missed. That is, if you did sample the sound at the rate shown, and then tried to reconstruct the signal from the samples, what you would get would look like this: High Frequency Sound -------------------- * A * | * | A * * | | * | | A * * | | | * * | | | A | | | | | | | | | | | | Sound Samples Which does not look like the original signal at all. The rule here is that the theoretical highest frequency which can be represented by a series of samples is the frequency equal to half of the sampling rate. This frequency is called the Nyquist frequency. As it turns out, however, the real application of PCM recording and play- back is slightly more restrictive even than this. If you again examine the figures above showing the result of attempting to sample a frequency higher than the Nyquist frequency, you will notice that not only is the reconstructed signal not the original, it is in fact a different signal. This effect is called "aliasing." Essentially, as one attempts to sample a frequency higher than the Nyquist frequency, what one gets is an "image" which is a tone whose frequency is equal to the sample rate minus the frequency of the original tone. For example: Appendix C. Additional Information on PCM Support 72 ∙ You select a record sampling rate of 11025 samples per second. ∙ The Nyquist frequency is 11025/2 = 5512 Hertz. ∙ You attempt to sample a tone of 7000 Hertz. ∙ The tone recorded will "look like" a tone of 11025 - 7000 = 4025 Hertz. In order to prevent this sort of "aliasing," the PCM support microcode must digitally filter out frequencies higher than the Nyquist frequency for each sampling rate. In an ideal world (of unlimited free digital signal processing power) one could have a so-called "brick-wall" filter which would leave frequencies below the Nyquist frequency completely undisturbed and also absolutely and completely eliminate any frequency above the Nyquist frequency. Real digital filters, however, are not so perfectly precise and must be designed with a certain amount of safety. The approximate bandwidth of the current PCM support for the M-ACPA at different sample rates is shown below: Sample Rate Maximum Frequency ----------- ----------------- 8000 samples/sec 3000 Hertz 11025 samples/sec 4450 Hertz 22050 samples/sec 9200 Hertz 44100 samples/sec 20000 Hertz C.1.2 SAMPLE WIDTH The sound quality is also greatly affected by the number of bits used to store each sound sample. The choices for storing sound samples are: ∙ 8-bit integer ∙ 16-bit integer ∙ effective 14-bit integer (mu-Law) (see C.2, "Mu-Law and A-Law Companding" on page 76) ∙ effective 13-bit integer (A-Law) (see C.2, "Mu-Law and A-Law Companding" on page 76) The significant effect of the number of bits used is the amount of back- ground hiss perceived by the listener. This hiss is actually the audible effect of quantization error or the error introduced when the continuously variable sound level is assigned to the nearest integer for storage as a sample. Appendix C. Additional Information on PCM Support 73 Consider the following portion of a sound signal which we would like to sample: Nearest Integer Sample Value | V * 37 * * * 36 * * * 35 * * * * 34 * In order to sample the signal we will have to determine at fixed intervals which of the available integer sample values was nearest to the signal: Nearest Integer Sample Value | V * 37 - - - - - - - - * - * * 36 - - - - - - - - - - * * * 35 - - - * - - - - - - * * * 34 * - - - - - - - - - The resulting signal ends up sort of "squared off" looking something like this: Appendix C. Additional Information on PCM Support 74 Nearest Integer Sample Value | V * | 37 - - - - - - - .------*--' - * | * | 36 - - - - - - .--------' - - | * * * | 35 - - .---------*-------------' - - - - | * * * | 34 *--------' - - - - - - - - However, the new "square" version of the signal is definitely not the same as the old smooth version. In fact, the new version is equivalent to the sum of the original version of the signal and an error signal which looks like this: 1/2 * * * * * * * * * 0 * * * * * * * * * * * * -1/2 * * * This error is in fact random and uniformly distributed on the interval between -1/2 and 1/2. If you consider the error to be a signal, it has an RMS value of 1/(2 * square-root(3)) or approximately 0.3. Now, if we use 8-bit numbers to represent the full scale of our sampled sound, in the best case, a signal can range from -128 to +127. If the sound is a pure tone, or sine wave, it has a RMS value of 127/square-root(2) or approximately 90. In this case, the volume of the noise represents 0.3/90 or 1/3 percent of the volume of the signal. Alternatively stated, the signal to noise ratio is 20 * log10 ( 90 / 0.3) = 49.5 dB. The signal is 300 times louder than the noise. In the lucky case where you are recording only sounds of all the same volume (loud) this noise will not be a problem. Unfortunately, most reasonably good music has a much wider range of small and large sounds than this. The sound of a symphony orchestra going full bore is on the order of 10,000 times louder (from a sound pressure level point of view) than the sound of the lone piccolo playing. Clearly if we set our sample scale to be able to capture the full orchestra, the sound of the piccolo will be lost in the quantization noise if we use an 8-bit scale. Appendix C. Additional Information on PCM Support 75 The solution to this problem is to use a 16-bit scale. Now our loudest signal can range from -32768 to 32767. The error, however, still is on the order of 0.3, just like before. The full scale sine wave will now have a RMS value of 32767/square-root(2) or approximately 23,170. In this case, the ratio of the loudest signal to the noise is 23,170/0.3 which is approximately equal to 77,200. We now have more than enough dynamic range to take care of the the piccolo to full-orchestra span of volume. The the- oretical maximum signal to noise ratio is 20 * log10 (77,200) = 98 dB (approximately). There are two things to note about this number: 1. The actual performance of the M-ACPA is less than this. However, expe- rience here is that the noise performance of of the M-ACPA is good enough so that most of the time other factors such as noise in the cables, power-line hum in the amplifier, and so on are sufficient to mask any noise introduced by the M-ACPA. 2. Some less-than-scrupulous stereo manufacturers (almost all of them actually) manage to use convoluted assumptions like: "the customer will be listening to nothing but square waves" to skew this calcu- lation to show even higher signal to noise numbers for their CD players. 3. In point of practice, in any environment other than an anechoic chamber with several thousand dollars worth of the very best high fidelity studio audio equipment, anything better than about 50 dB of signal to noise ratio sounds wonderful to the average listener. C.2 MU-LAW AND A-LAW COMPANDING ________________________________ The problem with using 16-bit integer samples rather than 8-bit integer samples is that doing so doubles the amount of disk space required to store the information. The companies involved in designing digital telephone transmission equip- ment ran up against this problem long ago and have developed a solution which works remarkably well. They use a non-linear scale to code the sound samples into 8-bit values. Appendix C. Additional Information on PCM Support 76 Mu-Law Companding Curve ----------------------- 127 + - --- 8 | - | - b | i | - t | 63 | - v | - a | l | - u | e |- 0 +-----------+----------+----------+---------- 2048 4096 6144 8159 14-bit signed sample value The actual digital to analog converter uses either a 13 or 14 bit signed integer scale. The number obtained is then mapped to an 8-bit number as shown for storage or transmission. There are two mapping curves in common use in the telephony world for this purpose: Mu-Law Maps a signed 14-bit number to an 8-bit number. Mu-law is used in the telephone networks of the United States, Canada, Japan, Hong Kong, Taiwan, and Korea. A-Law Maps a signed 13-bit number to an 8-bit number. A-law is used in the telephone networks of all countries other than the ones which use mu-Law. Both of these companding schemes effectively achieve an apparently higher signal to noise ratio by intentionally distorting louder signals. The assumption here is that most of what is being recorded is smaller scale signals most of the time. For example: 1. With 8-bit linear encoding, the quantizing error has an RMS value of 0.3 regardless of whether the input signal has an RMS value of 90 (loud) or an RMS value of 5 (rather soft). For the soft signal, the hiss is 0.3/5 = 6 percent as loud as the signal which is very notice- able with good audio equipment. That is, the small signal would have a signal to noise ratio of only 24 dB. 2. By comparison, with mu-law encoding, the largest possible signal will have an RMS value of 8159/square-root(2)(1) which is approximately 5768. However, the steps at the upper end of the mu-law curve are in units of 256. The RMS value of the quantization noise will therefore ─────────────── (1) The mu-law scale does not go quite all the way to 8192. Appendix C. Additional Information on PCM Support 77 be 128/square-root(3) or about 74. This will give a signal to noise ratio for the loud signal of about 20 * log10(5768/74) = 38 dB. 3. The comparable small signal is 5 / 128 * 8159 = 318 on the mu-law scale. In this range, the mu-law companding curve has a step size of 16. The RMS value of the quantization noise will therefore be 8/square-root(3) or about 4.6. This will give a signal to noise ratio for the loud signal of about 20 * log10(318/4.6) = 36 dB. The net effect of mu-law companding is to evenly scale the quantization noise so that the signal to noise ratio is always about 37 dB regardless of how loud or soft the signal is. Mu-Law and A-Law are always 8-bit and can be supported at any sample rate stereo or mono except 44100 samples per second stereo. Only a single track of mu-Law or A-law PCM can be played back at one time. The exact definitions of mu-Law and A-Law companding are available in recommendation G.711 of the CCITT (the United Nations body which sets international telephony agreements). C.3 DITHER ___________ For applications which require recording of 8-bit linear data (and to a lesser extent 14-bit mu-law and 13-bit A-law data) the use of dither can significantly improve the quality of the recording of softer signals. The problem alleviated by dither is that of the extreme relative dis- tortion of signals whose magnitude is on the order of one bit. Consider a pure tone whose amplitude is just around one bit. 3 * * * * * * * * * * * * * * * * * 2 * * * * * (The tone shown above has a peak to peak amplitude of 1 and a DC offset of 2.5) When quantized, this signal will tend to turn very square: Appendix C. Additional Information on PCM Support 78 3 .------*--------. .------*---------. | * * | | * * | | | | * * | * * | | | | | * | *| * | * | | | | | | * * | *| | | | | 2 ----' '--*-------*-----' '-*------ * * A square wave like this essentially represents the original tone with a tremendous amount of harmonic distortion thrown into it. The tone will sound very rough and grating. Further problems arise if the amplitude of the tone is varying slightly over time. If the amplitude of the signal shown above were to decrease slightly, it would simply disappear. A short while later it might reappear again as the amplitude once again became greater than one bit. This phenomenon can be heard easily with good audio equipment by making an 8-bit recording (with dither disabled - 0 percent) of something like a French Horn solo trailing delicately off to silence. As the sound dies away, a very unpleasant crackling noise will be heard. Dither attacks this problem by inserting a small amount of random noise into the signal before quantizing from 16-bits down to 8-bits (or down to 14 or 13 bits in the case of mu-Law and A-Law). The size of the signal is user selectable to be scaled to a range of up to +/- one bit. The default range for dither is +/- 1/3 bit. That is, in the normal case, the M-ACPA microcode generates a series of random numbers which have magnitudes between -1 and 1 and then multiplies them by (the user specified value of) 33/100 and adds them to the signal before quantizing to 8 bits. This dither has the effect of randomizing the transitions between quantization levels. The signal shown above might look like this if dithered with 1/3 bit of noise before quantization: 3 .---. *.-------. .--. .*---------. | *| | * | | | * | * | | | | | | | | * | | * | | * | * | | | | | | | | | * | | | *| |* | | * | | | | | | | | | | | | * * | | *| | | | | | | | | 2 ----' '---' '--*-------*--' '-----' '-*------ * * Dither has two effects in this instance: Appendix C. Additional Information on PCM Support 79 1. The shape of the resulting wave is now no longer regular. This irreg- ular random shape tends to eliminate the harmonics of the fundamental tone present in the square wave. 2. Because of the occasional addition of +1/3 bit to a high point on the signal or -1/3 bit to a low point on the signal, the signal will not die out completely until it falls below a peak to peak amplitude of 1/3 bit, considerably smaller than without dither. What is not intuitively obvious but is born out in theory and in practice is that the original tone is still present in the randomized and quantized signal shown above! That is, if you average the irregular dithered signal over time, the average will converge to the original tone again. The net effect is that by adding some additional background hiss, small signals will die out smoothly. If the French Horn solo recording test described above is repeated with 50 percent dither, the sound of the horn will fade gently into the background hiss without breaking up. Dithering should be quite useful for those needing to produce 8-bit linear recordings of as high a quality as possible. Note, however, that the actual level of the dither is really a matter of subjective opinion. There is no "right" answer. The more dither you add, the better the signal sounds, but the more background hiss you hear as well. Many textbooks suggest 33 percent as a good compromise and this is the default value. C.4 VOLUME, BALANCE, RAMP AND PAN __________________________________ The M-ACPA supports the use of volume controls for both record and play- back. In the record case, the volume controls affect the volume of the data being recorded as well as the volume of the monitor. In the playback case, there is a separate and independent set of volume controls for each track. C.4.1 MASTER VOLUME The master volume is the overall volume setting for the track. 1. Once recording or playback has begun, the master volume can not be changed. 2. The scale for master volume is 0 to 116. a. The master volume scale is a logarithmic scale. b. The default master volume is 100. c. A value of 100 neither amplifies nor attenuates a signal. A full scale signal coming into the M-ACPA input ports will be recorded as a full scale signal in the sound file. A full scale signal in the sound file, will be played as a full scale signal from the M-ACPA output ports. Appendix C. Additional Information on PCM Support 80 d. An increase of 8 in the master volume setting doubles the voltage of the signal being output by the M-ACPA. On record, an increase of 8 in the master volume setting doubles the numerical value of the samples being stored. e. The maximum track volume setting of 116 increases the voltage of the signal being played by 4 which increases its power by 16. The maximum of 116 represents an amplification of +12dB. f. An decrease of 8 in the master volume setting halves the voltage of the signal being output by the M-ACPA. On record, an decrease of 8 in the master volume setting halves the numerical value of the samples being stored. The ability to increase the volume is useful for some audio devices which can not supply a standard full scale audio signal to the M-ACPA line in ports. Note, however, that by amplifying the input signal by 12 dB, you are effectively losing 2 bits of resolution in your signal. From the point of view of quantization noise, you are now dealing with a 14-bit signal rather than a 16-bit signal. This effect, however, does not seem to be perceptible even with very high quality audio equipment. C.4.2 TRACK VOLUME Track volume is used to modify the master volume. The track volume can be changed during record or playback. The track volume ranges from 0 to 100 percent and indicates the percentage of the current master volume to use. Note that this is a linear modification of the logarithmic master volume. Setting master volume to 100 and track volume to 50 percent, will set the volume as though you had set the master volume to 50. C.4.3 RAMP RATE A ramp (up or down) can be initiated by changing the current track volume and specifying a number of milliseconds for the change to take place. For example: 1. The master volume is set to 100. 2. The track volume is set to 100. 3. The track volume is changed to 50 and a ramp time of 5000 milliseconds is specified. 4. After 1 second the effective track volume will have changed to 90. 5. After 2 seconds the effective track volume will have changed to 80. 6. After 5 seconds the ramp will be complete and the new effective track volume level will be 50. Appendix C. Additional Information on PCM Support 81 The ramp will sound very smooth and continuous to a human ear even though the actual voltage levels are changing in a logarithmic fashion; such is the nature of the human ear. It is possible to interrupt a ramp in progress and set a new target level to ramp to. In this case, the ramp will be between the last effective level (when the ramp in progress was interrupted by a new change in track volume) and the new track volume. The new ramp will take the number of milliseconds specified at the time the new ramp is initiated. C.4.4 BALANCE The balance control can be thought of as "percentage of the way to the right." The default of 50 percent means that the volume is split evenly between right and left. 100 percent means that the volume is all the way to the right; 0 percent indicates all the way to the left. The basic operation of balance is to modify track volume which in turn modifies master volume. The actual operation of the balance, however, is not so simple. The major complication arises from the human perception of sound levels. Whereas the human perceives absolute sound levels in a logarithmic fashion, unfortunately the human perceives relative balance of sound levels (left to right) in a linear fashion! If we are ever to hope to make a pan (side to side) operate smoothly like a ramp (up and down) this difference in human perception forces us to use a non-linear balance scale to compensate for the logarithmic master volume scale. The effect of balance settings on volume looks like this: 116 +L R | L R | L R 100 + - - - R - - - - | | R | L | | R | L | | R | L | | R | L | | R | L 0 +------------------------------------------------ 0 50 100 Percent Right ------------- At the default of 50 percent, balance has no effect on volume. As the volume shifts to one side, it increases the volume on that side above 100 percent while decreasing the volume on the other side. Appendix C. Additional Information on PCM Support 82 Note that the maximum is still 116. If the master volume is set to 116 and the balance is moved to one side, the balance curve will limit itself as it gets to 116. This effect will not impair the sense of balance, but it will degrade the smoothness and evenness of a panning action. C.4.5 PAN RATE Pan rate is to balance what ramp rate is to track volume. A pan (left or right) can be initiated by changing the current balance and specifying a number of milliseconds for the change to take place. For example: 1. The master volume is set to 100. 2. The track volume is set to 100. 3. The balance is set to 50. 4. The balance is changed to 0 and a pan time of 5000 milliseconds is specified. 5. Balance will pan smoothly to the left over 5 seconds. The pan will sound reasonably smooth and continuous to a human ear unless the application has also simultaneously requested the amplification of the signal (master volume > 100). C.5 SOURCE MIXING __________________ Source mixing can be used to add the input from either of the M-ACPA input ports into the output of PCM being played back. 1. Source mix can either be played on its own track or together with a PCM file on a track. 2. Since stereo playback requires single track operation, source mix must be played on the same track as the PCM to mix over a stereo track. 3. Playing source mix on its own track with another track of mono PCM allows each to have independent volume, balance, ramp and fade con- trols. 4. The options for input for source mix are microphone, low gain micro- phone, or stereo line in (both). Input from only stereo line left or only stereo line right is not supported. 5. If stereo line both is used as an input and the PCM file being played is stereo, the source mix will be stereo as well. That is, the left channel of the source will be mixed with the left channel of the PCM data and the right channel of the source will be mixed with the right channel of the PCM data. Appendix C. Additional Information on PCM Support 83 All other combinations of input and PCM data will cause source mix to be monophonic. Appendix C. Additional Information on PCM Support 84